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 PostgreSQL documentation
--> -->
@ -10,166 +10,40 @@ PostgreSQL documentation
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>CREATE AGGREGATE</refname>
CREATE AGGREGATE <refpurpose>define a new aggregate function</refpurpose>
</refname>
<refpurpose>
define a new aggregate function
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>2000-07-16</date> CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> (
</refsynopsisdivinfo> BASETYPE = <replaceable class="PARAMETER">input_data_type</replaceable>,
<synopsis> SFUNC = <replaceable class="PARAMETER">sfunc</replaceable>,
CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( BASETYPE = <replaceable class="PARAMETER">input_data_type</replaceable>, STYPE = <replaceable class="PARAMETER">state_data_type</replaceable>
SFUNC = <replaceable class="PARAMETER">sfunc</replaceable>, STYPE = <replaceable class="PARAMETER">state_type</replaceable>
[ , FINALFUNC = <replaceable class="PARAMETER">ffunc</replaceable> ] [ , FINALFUNC = <replaceable class="PARAMETER">ffunc</replaceable> ]
[ , INITCOND = <replaceable class="PARAMETER">initial_condition</replaceable> ] ) [ , INITCOND = <replaceable class="PARAMETER">initial_condition</replaceable> ]
</synopsis> )
</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>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-CREATEAGGREGATE-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>2000-07-16</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>CREATE AGGREGATE</command> <command>CREATE AGGREGATE</command> defines a new aggregate function. Some aggregate functions
allows a user or programmer to extend <productname>PostgreSQL</productname>
functionality by defining new aggregate functions. Some aggregate functions
for base types such as <function>min(integer)</function> 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 distribution. If one defines new types or needs an aggregate function not
already provided, then <command>CREATE AGGREGATE</command> already provided, then <command>CREATE AGGREGATE</command>
can be used to provide the desired features. can be used to provide the desired features.
</para> </para>
<para> <para>
If a schema name is given (for example, <literal>CREATE AGGREGATE If a schema name is given (for example, <literal>CREATE AGGREGATE
myschema.myagg ...</>) then the aggregate function is created in the myschema.myagg ...</>) then the aggregate function is created in the
specified schema. Otherwise it is created in the current schema (the one specified schema. Otherwise it is created in the current schema.
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
</para> </para>
<para> <para>
An aggregate function is identified by its name and input data type. 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 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 the name and input data type(s) of every ordinary function in the same
schema. schema.
</para> </para>
<para> <para>
An aggregate function is made from one or two ordinary An aggregate function is made from one or two ordinary
functions: functions:
@ -186,11 +61,12 @@ CREATE AGGREGATE
and an optional final calculation function and an optional final calculation function
<replaceable class="PARAMETER">ffunc</replaceable>. <replaceable class="PARAMETER">ffunc</replaceable>.
These are used as follows: These are used as follows:
<programlisting> <programlisting>
<replaceable class="PARAMETER">sfunc</replaceable>( internal-state, next-data-item ) ---> next-internal-state <replaceable class="PARAMETER">sfunc</replaceable>( internal-state, next-data-item ) ---> next-internal-state
<replaceable class="PARAMETER">ffunc</replaceable>( internal-state ) ---> aggregate-value <replaceable class="PARAMETER">ffunc</replaceable>( internal-state ) ---> aggregate-value
</programlisting> </programlisting>
</para> </para>
<para> <para>
<productname>PostgreSQL</productname> creates a temporary variable <productname>PostgreSQL</productname> creates a temporary variable
of data type <replaceable class="PARAMETER">stype</replaceable> of data type <replaceable class="PARAMETER">stype</replaceable>
@ -198,7 +74,7 @@ CREATE AGGREGATE
data item, data item,
the state transition function is invoked to calculate a new the state transition function is invoked to calculate a new
internal state value. After all the data has been processed, 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 value. If there is no final function then the ending state value
is returned as-is. is returned as-is.
</para> </para>
@ -206,67 +82,163 @@ CREATE AGGREGATE
<para> <para>
An aggregate function may provide an initial condition, An aggregate function may provide an initial condition,
that is, an initial value for the internal state value. 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 <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 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>
<para> <para>
If the state transition function is declared <quote>strict</quote>, If the state transition function is declared <quote>strict</quote>,
then it cannot be called with NULL inputs. With such a transition then it cannot be called with null inputs. With such a transition
function, aggregate execution behaves as follows. NULL input values function, aggregate execution behaves as follows. Null input values
are ignored (the function is not called and the previous state value are ignored (the function is not called and the previous state value
is retained). If the initial state value is NULL, then the first is retained). If the initial state value is null, then the first
non-NULL input value replaces the state value, and the transition nonnull input value replaces the state value, and the transition
function is invoked beginning with the second non-NULL input value. function is invoked beginning with the second nonnull input value.
This is handy for implementing aggregates like <function>max</function>. This is handy for implementing aggregates like <function>max</function>.
Note that this behavior is only available when 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 is the same as
<replaceable class="PARAMETER">input_data_type</replaceable>. <replaceable class="PARAMETER">input_data_type</replaceable>.
When these types are different, you must supply a non-NULL initial When these types are different, you must supply a nonnull initial
condition or use a non-strict transition function. condition or use a nonstrict transition function.
</para> </para>
<para> <para>
If the state transition function is not strict, then it will be called If the state transition function is not strict, then it will be called
unconditionally at each input value, and must deal with NULL inputs unconditionally at each input value, and must deal with null inputs
and NULL transition values for itself. This allows the aggregate and null transition values for itself. This allows the aggregate
author to have full control over the aggregate's handling of null values. author to have full control over the aggregate's handling of null values.
</para> </para>
<para> <para>
If the final function is declared <quote>strict</quote>, then it will not 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 be called when the ending state value is null; instead a null result
will be output automatically. (Of course this is just the normal will be returned automatically. (Of course this is just the normal
behavior of strict functions.) In any case the final function has behavior of strict functions.) In any case the final function has
the option of returning NULL. For example, the final function for the option of returning a null value. For example, the final function for
<function>avg</function> returns NULL when it sees there were zero <function>avg</function> returns null when it sees there were zero
input tuples. input rows.
</para> </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>
<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> <title>Examples</title>
<para> <para>
@ -274,24 +246,14 @@ CREATE AGGREGATE
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-CREATEAGGREGATE-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-CREATEAGGREGATE-4"> <para>
<refsect2info> <command>CREATE AGGREGATE</command> is a
<date>1998-09-09</date> <productname>PostgreSQL</productname> language extension. The SQL
</refsect2info> standard does not provide for user-defined aggregate function.
<title> </para>
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>
</refsect1> </refsect1>
</refentry> </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"> <refentry id="SQL-CREATECAST">
<refmeta> <refmeta>
@ -58,11 +58,11 @@ SELECT CAST(42 AS text);
<para> <para>
If the cast is marked <literal>AS ASSIGNMENT</> then it can be invoked 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 For example, supposing that <literal>foo.f1</literal> is a column of
type <type>text</type>, then type <type>text</type>, then
<programlisting> <programlisting>
INSERT INTO foo(f1) VALUES(42); INSERT INTO foo (f1) VALUES (42);
</programlisting> </programlisting>
will be allowed if the cast from type <type>integer</type> to type will be allowed if the cast from type <type>integer</type> to type
<type>text</type> is marked <literal>AS ASSIGNMENT</>, otherwise <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 If the cast is marked <literal>AS IMPLICIT</> then it can be invoked
implicitly in any context, whether assignment or internally in an implicitly in any context, whether assignment or internally in an
expression. For example, since <literal>||</> takes <type>text</> expression. For example, since <literal>||</> takes <type>text</>
arguments, operands,
<programlisting> <programlisting>
SELECT 'The time is ' || now(); SELECT 'The time is ' || now();
</programlisting> </programlisting>
@ -106,14 +106,16 @@ SELECT 'The time is ' || CAST(now() AS text);
<para> <para>
To be able to create a cast, you must own the source or the target 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 data type. To create a binary-compatible cast, you must be superuser.
(this restriction is made because an erroneous binary-compatible cast (This restriction is made because an erroneous binary-compatible cast
conversion can easily crash the server). conversion can easily crash the server.)
</para> </para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist> <variablelist>
<title>Parameters</title>
<varlistentry> <varlistentry>
<term><replaceable>sourcetype</replaceable></term> <term><replaceable>sourcetype</replaceable></term>
@ -183,6 +185,21 @@ SELECT 'The time is ' || CAST(now() AS text);
</refsect1> </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"> <refsect1 id="sql-createcast-notes">
<title>Notes</title> <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. argument of a different type was automatically a cast function.
This convention has been abandoned in face of the introduction of This convention has been abandoned in face of the introduction of
schemas and to be able to represent binary compatible casts in the schemas and to be able to represent binary compatible casts in the
catalogs. (The built-in cast functions still follow this naming system catalogs. (The built-in cast functions still follow this naming
scheme, but they have to be shown as casts in <literal>pg_cast</> scheme, but they have to be shown as casts in the system catalog <literal>pg_cast</>
now.) now.)
</para> </para>
</refsect1> </refsect1>
@ -227,7 +244,7 @@ CREATE CAST (text AS int4) WITH FUNCTION int4(text);
<para> <para>
The <command>CREATE CAST</command> command conforms to SQL99, 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> types. <literal>AS IMPLICIT</> is a <productname>PostgreSQL</productname>
extension, too. extension, too.
</para> </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 PostgreSQL documentation
--> -->
@ -8,30 +8,35 @@ PostgreSQL documentation
<refentrytitle id="sql-createconstraint-title">CREATE CONSTRAINT TRIGGER</refentrytitle> <refentrytitle id="sql-createconstraint-title">CREATE CONSTRAINT TRIGGER</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>CREATE CONSTRAINT TRIGGER</refname>
CREATE CONSTRAINT TRIGGER <refpurpose>define a new constraint trigger</refpurpose>
</refname>
<refpurpose>
define a new constraint trigger
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>2000-04-13</date>
</refsynopsisdivinfo>
<synopsis>
CREATE CONSTRAINT TRIGGER <replaceable class="parameter">name</replaceable> CREATE CONSTRAINT TRIGGER <replaceable class="parameter">name</replaceable>
AFTER <replaceable class="parameter">events</replaceable> ON AFTER <replaceable class="parameter">events</replaceable> ON
<replaceable class="parameter">relation</replaceable> <replaceable class="parameter">constraint</replaceable> <replaceable class="parameter">attributes</replaceable> <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> ')' FOR EACH ROW EXECUTE PROCEDURE <replaceable class="parameter">func</replaceable> ( <replaceable class="parameter">args</replaceable> )
</synopsis> </synopsis>
</refsynopsisdiv>
<refsect2 id="R2-SQL-CREATECONSTRAINT-1"> <refsect1>
<title> <title>Description</title>
Inputs
</title> <para>
<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> <variablelist>
<varlistentry> <varlistentry>
@ -53,10 +58,10 @@ CREATE CONSTRAINT TRIGGER <replaceable class="parameter">name</replaceable>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><replaceable class="PARAMETER">relation</replaceable></term> <term><replaceable class="PARAMETER">table</replaceable></term>
<listitem> <listitem>
<para> <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. the triggering events occur.
</para> </para>
</listitem> </listitem>
@ -75,7 +80,7 @@ CREATE CONSTRAINT TRIGGER <replaceable class="parameter">name</replaceable>
<term><replaceable class="PARAMETER">attributes</replaceable></term> <term><replaceable class="PARAMETER">attributes</replaceable></term>
<listitem> <listitem>
<para> <para>
Constraint attributes. The constraint attributes.
</para> </para>
</listitem> </listitem>
</varlistentry> </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> <term><replaceable class="PARAMETER">func</replaceable>(<replaceable class="PARAMETER">args</replaceable>)</term>
<listitem> <listitem>
<para> <para>
Function to call as part of the trigger processing. The function to call as part of the trigger processing.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para> </refsect1>
</refsect2>
<refsect2 id="R2-SQL-CREATECONSTRAINT-2"> <refsect1>
<title> <title>Diagnostics</title>
Outputs
</title>
<para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><computeroutput> <term><computeroutput>CREATE TRIGGER</computeroutput></term>
CREATE TRIGGER
</computeroutput></term>
<listitem> <listitem>
<para> <para>
Message returned if successful. Message returned if successful.
@ -110,24 +109,6 @@ CREATE TRIGGER
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </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> </refsect1>
</refentry> </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"> <refentry id="SQL-CREATECONVERSION">
<refmeta> <refmeta>
@ -23,21 +23,24 @@ CREATE [DEFAULT] CONVERSION <replaceable>conversion_name</replaceable>
<para> <para>
<command>CREATE CONVERSION</command> defines a new encoding <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 to specify a particular encoding conversion. Also, conversions that
are marked DEFAULT can be used for automatic encoding conversion between are marked <literal>DEFAULT</> can be used for automatic encoding conversion between
frontend and backend. For this purpose, two conversions, from encoding A to client and server. For this purpose, two conversions, from encoding A to
B AND from encoding B to A, must be defined. B <emphasis>and</emphasis> from encoding B to A, must be defined.
</para> </para>
<para> <para>
To be able to create a conversion, you must have the execute right To be able to create a conversion, you must have <literal>EXECUTE</literal> privilege
on the function and the create right on the destination schema. on the function and <literal>CREATE</literal> privilege on the destination schema.
</para> </para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist> <variablelist>
<title>Parameters</title>
<varlistentry> <varlistentry>
<term><literal>DEFAULT</literal></term> <term><literal>DEFAULT</literal></term>
@ -75,7 +78,7 @@ CREATE [DEFAULT] CONVERSION <replaceable>conversion_name</replaceable>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><replaceable>source_encoding</replaceable></term> <term><replaceable>dest_encoding</replaceable></term>
<listitem> <listitem>
<para> <para>
@ -92,25 +95,39 @@ CREATE [DEFAULT] CONVERSION <replaceable>conversion_name</replaceable>
The function used to perform the conversion. The function name may The function used to perform the conversion. The function name may
be schema-qualified. If it is not, the function will be looked be schema-qualified. If it is not, the function will be looked
up in the path. up in the path.
</para> </para>
<para> <para>
The function must have the following signature: The function must have the following signature:
<programlisting> <programlisting>
conv_proc( conv_proc(
INTEGER, -- source encoding id integer, -- source encoding ID
INTEGER, -- destination encoding id integer, -- destination encoding ID
CSTRING, -- source string (null terminated C string) cstring, -- source string (null terminated C string)
CSTRING, -- destination string (null terminated C string) cstring, -- destination string (null terminated C string)
INTEGER -- source string length integer -- source string length
) returns VOID; ) RETURNS void;
</programlisting> </programlisting>
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </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>
<refsect1 id="sql-createconversion-notes"> <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 The privileges required to create a conversion may be changed in a future
release. release.
</para> </para>
</refsect1> </refsect1>
<refsect1 id="sql-createconversion-examples"> <refsect1 id="sql-createconversion-examples">
<title>Examples</title> <title>Examples</title>
<para> <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> <programlisting>
CREATE CONVERSION myconv FOR 'UNICODE' TO 'LATIN1' FROM myfunc; CREATE CONVERSION myconv FOR 'UNICODE' TO 'LATIN1' FROM myfunc;
</programlisting> </programlisting>
@ -147,7 +163,7 @@ CREATE CONVERSION myconv FOR 'UNICODE' TO 'LATIN1' FROM myfunc;
<command>CREATE CONVERSION</command> <command>CREATE CONVERSION</command>
is a <productname>PostgreSQL</productname> extension. is a <productname>PostgreSQL</productname> extension.
There is no <command>CREATE CONVERSION</command> There is no <command>CREATE CONVERSION</command>
statement in <acronym>SQL99</acronym>. statement in the SQL standard.
</para> </para>
</refsect1> </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 PostgreSQL documentation
--> -->
@ -8,34 +8,81 @@ PostgreSQL documentation
<refentrytitle id="sql-createdatabase-title">CREATE DATABASE</refentrytitle> <refentrytitle id="sql-createdatabase-title">CREATE DATABASE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>CREATE DATABASE</refname>
CREATE DATABASE <refpurpose>create a new database</refpurpose>
</refname>
<refpurpose>
create a new database
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-12-11</date>
</refsynopsisdivinfo>
<synopsis>
CREATE DATABASE <replaceable class="PARAMETER">name</replaceable> CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
[ [ WITH ] [ OWNER [=] <replaceable class="parameter">dbowner</replaceable> ] [ [ WITH ] [ OWNER [=] <replaceable class="parameter">dbowner</replaceable> ]
[ LOCATION [=] '<replaceable class="parameter">dbpath</replaceable>' ] [ LOCATION [=] '<replaceable class="parameter">dbpath</replaceable>' ]
[ TEMPLATE [=] <replaceable class="parameter">template</replaceable> ] [ TEMPLATE [=] <replaceable class="parameter">template</replaceable> ]
[ ENCODING [=] <replaceable class="parameter">encoding</replaceable> ] ] [ ENCODING [=] <replaceable class="parameter">encoding</replaceable> ] ]
</synopsis> </synopsis>
</refsynopsisdiv>
<refsect2 id="R2-SQL-CREATEDATABASE-1"> <refsect1>
<refsect2info> <title>Description</title>
<date>1999-12-11</date>
</refsect2info> <para>
<title> <command>CREATE DATABASE</command> creates a new
Inputs <productname>PostgreSQL</productname> database.
</title> </para>
<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> <variablelist>
<varlistentry> <varlistentry>
@ -50,7 +97,7 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
<term><replaceable class="parameter">dbowner</replaceable></term> <term><replaceable class="parameter">dbowner</replaceable></term>
<listitem> <listitem>
<para> <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 or <literal>DEFAULT</literal> to use the default (namely, the
user executing the command). user executing the command).
</para> </para>
@ -70,7 +117,7 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
<term><replaceable class="parameter">template</replaceable></term> <term><replaceable class="parameter">template</replaceable></term>
<listitem> <listitem>
<para> <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 or <literal>DEFAULT</literal> to use the default template
(<literal>template1</literal>). (<literal>template1</literal>).
</para> </para>
@ -80,32 +127,30 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
<term><replaceable class="parameter">encoding</replaceable></term> <term><replaceable class="parameter">encoding</replaceable></term>
<listitem> <listitem>
<para> <para>
Multibyte encoding method to use in the new database. Specify Character set encoding to use in the new database. Specify
a string literal name (e.g., <literal>'SQL_ASCII'</literal>), a string constant (e.g., <literal>'SQL_ASCII'</literal>),
or an integer encoding number, or <literal>DEFAULT</literal> or an integer encoding number, or <literal>DEFAULT</literal>
to use the default encoding. to use the default encoding.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-CREATEDATABASE-2"> <para>
<refsect2info> Optional parameters can be written in any order, not only the order
<date>1999-12-11</date> illustrated above.
</refsect2info> </para>
<title> </refsect1>
Outputs
</title> <refsect1>
<para> <title>Diagnostics</title>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><computeroutput>CREATE DATABASE</computeroutput></term> <term><computeroutput>CREATE DATABASE</computeroutput></term>
<listitem> <listitem>
<para> <para>
Message returned if the command completes successfully. Message returned if the database was successfully created.
</para> </para>
</listitem> </listitem>
</varlistentry> </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> <term><computeroutput>ERROR: createdb: database "<replaceable class="parameter">name</replaceable>" already exists</computeroutput></term>
<listitem> <listitem>
<para> <para>
This occurs if a database with the <replaceable class="parameter">name</replaceable> This occurs if a database with the specified name already
specified already exists. exists.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -166,186 +211,73 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para> </refsect1>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-CREATEDATABASE-1"> <refsect1>
<refsect1info> <title>Notes</title>
<date>1999-12-11</date>
</refsect1info>
<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
<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> <para>
Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database. Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database.
</para> </para>
<para> <para>
The program <xref linkend="APP-CREATEDB" endterm="APP-CREATEDB-title"> is a 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>
<para> <para>
There are security and data integrity issues There are security issues involved with using alternate database
involved with using alternate database locations locations specified with absolute path names. See <xref
specified with absolute path names, and by default linkend="manage-ag-alternate-locs"> for more information.
only an environment variable known to the backend may be </para>
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> <para>
Although it is possible to copy a database other than <literal>template1</> 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 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. 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> </para>
</refsect2>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-CREATEDATABASE-2"> <refsect1>
<title> <title>Examples</title>
Usage
</title>
<para> <para>
To create a new database: To create a new database:
<programlisting> <programlisting>
<prompt>olly=></prompt> <userinput>create database lusiadas;</userinput> CREATE DATABASE lusiadas;
</programlisting> </programlisting>
</para> </para>
<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> <programlisting>
<prompt>$</prompt> <userinput>mkdir private_db</userinput> mkdir private_db
<prompt>$</prompt> <userinput>initlocation ~/private_db</userinput> initlocation ~/private_db
<computeroutput> </programlisting>
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
initlocation is complete. Then execute the following from within a
</computeroutput> <application>psql</application> session:
<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
<prompt>olly=></prompt></computeroutput> <userinput>CREATE DATABASE elsewhere WITH LOCATION = '/home/olly/private_db';</userinput> <programlisting>
<computeroutput>CREATE DATABASE</computeroutput> CREATE DATABASE elsewhere WITH LOCATION '/home/olly/private_db';
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-CREATEDATABASE-4"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-CREATEDATABASE-4"> <para>
<refsect2info> There is no <command>CREATE DATABASE</command> statement in the SQL
<date>1998-04-15</date> standard. Databases are equivalent to catalogs, whose creation is
</refsect2info> implementation-defined.
<title> </para>
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>
</refsect1> </refsect1>
</refentry> </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 PostgreSQL documentation
--> -->
<refentry id="SQL-CREATEDOMAIN"> <refentry id="SQL-CREATEDOMAIN">
<refmeta> <refmeta>
<refentrytitle id="sql-createdomain-title"> <refentrytitle id="sql-createdomain-title">CREATE DOMAIN</refentrytitle>
CREATE DOMAIN
</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>CREATE DOMAIN</refname>
CREATE DOMAIN <refpurpose>define a new domain</refpurpose>
</refname>
<refpurpose>
define a new domain
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>2002-02-24</date>
</refsynopsisdivinfo>
<synopsis>
CREATE DOMAIN <replaceable class="parameter">domainname</replaceable> [AS] <replaceable class="parameter">data_type</replaceable> CREATE DOMAIN <replaceable class="parameter">domainname</replaceable> [AS] <replaceable class="parameter">data_type</replaceable>
[ DEFAULT <replaceable>default_expr</> ] [ DEFAULT <replaceable>default_expr</> ]
[ <replaceable class="PARAMETER">constraint</replaceable> [ ... ] ] [ <replaceable class="PARAMETER">constraint</replaceable> [ ... ] ]
@ -31,16 +24,35 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
[ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ] [ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ]
{ NOT NULL | NULL | CHECK (<replaceable class="PARAMETER">expression</replaceable>) } { NOT NULL | NULL | CHECK (<replaceable class="PARAMETER">expression</replaceable>) }
</synopsis> </synopsis>
</refsynopsisdiv>
<refsect2 id="R2-SQL-CREATEDOMAIN-1"> <refsect1>
<refsect2info> <title>Description</title>
<date>2002-02-24</date>
</refsect2info> <para>
<title> <command>CREATE DOMAIN</command> creates a new data domain. The
Parameters user who defines a domain becomes its owner.
</title> </para>
<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> <variablelist>
<varlistentry> <varlistentry>
@ -63,32 +75,26 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><literal>DEFAULT <term><literal>DEFAULT <replaceable>default_expr</replaceable></literal></term>
<replaceable>default_expr</replaceable></literal></term>
<listitem> <listitem>
<para> <para>
The <literal>DEFAULT</> clause specifies a default value for The <literal>DEFAULT</> clause specifies a default value for
columns of the domain data type. The value columns of the domain data type. The value is any
is any variable-free expression (but subselects are not allowed). variable-free expression (but subqueries are not allowed).
The The data type of the default expression must match the data
data type of the default expression must match the data type of the type of the domain. If no default value is specified, then
domain. the default value is the null value.
</para> </para>
<para> <para>
The default expression will be used in any insert operation that The default expression will be used in any insert operation
does not specify a value for the column. If there is no default that does not specify a value for the column. If a default
for a domain, then the default is NULL. 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> </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> </listitem>
</varlistentry> </varlistentry>
@ -106,7 +112,7 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
<term><literal>NOT NULL</></term> <term><literal>NOT NULL</></term>
<listitem> <listitem>
<para> <para>
Values of this domain are not allowed to be NULL. Values of this domain are not allowed to be null.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -115,12 +121,12 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
<term><literal>NULL</></term> <term><literal>NULL</></term>
<listitem> <listitem>
<para> <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>
<para> <para>
This clause is only available for compatibility with This clause is only intended for compatibility with
non-standard SQL databases. Its use is discouraged in new nonstandard SQL databases. Its use is discouraged in new
applications. applications.
</para> </para>
</listitem> </listitem>
@ -139,84 +145,50 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
<para> <para>
Currently, <literal>CHECK</literal> expressions cannot contain 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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist>
</refsect1>
</variablelist> <refsect1>
</para> <title>Diagnostics</title>
</refsect2>
<refsect2 id="R2-SQL-CREATEDOMAIN-2"> <variablelist>
<refsect2info> <varlistentry>
<date>2002-02-24</date> <term><computeroutput>CREATE DOMAIN</computeroutput></term>
</refsect2info> <listitem>
<title> <para>
Outputs Message returned if the domain was successfully created.
</title> </para>
<para> </listitem>
</varlistentry>
<variablelist> </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>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Examples</title> <title>Examples</title>
<para> <para>
This example creates the <type>country_code</type> data type and then uses the This example creates the <type>country_code</type> data type and then uses the
type in a table definition: type in a table definition:
<programlisting> <programlisting>
CREATE DOMAIN country_code char(2) NOT NULL; 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> </programlisting>
</para> </para>
</refsect1> </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"> <refsect1 id="SQL-CREATEDOMAIN-see-also">
<title>See Also</title> <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"> <refentry id="SQL-CREATEFUNCTION">
@ -38,25 +38,48 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
</para> </para>
<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>
<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> <variablelist>
<title>Parameters</title>
<varlistentry> <varlistentry>
<term><replaceable class="parameter">name</replaceable></term> <term><replaceable class="parameter">name</replaceable></term>
<listitem> <listitem>
<para> <para>
The name of a function to create. If a schema name is included, The name of a function to create.
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</>).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -67,20 +90,21 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
<listitem> <listitem>
<para> <para>
The data type(s) of the function's arguments (optionally The data type(s) of the function's arguments (optionally
schema-qualified), if any. The input types may be base, complex, or schema-qualified), if any. The argument types may be base, complex, or
domain types, or the same as the type of an existing column. domain types, or copy the type of an existing column.
</para> </para>
<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">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 using this can sometimes help make a function independent from
changes to the definition of a table. changes to the definition of a table.
</para> </para>
<para> <para>
Depending on the implementation language it may also be allowed Depending on the implementation language it may also be allowed
to specify <quote>pseudo-types</> such as <type>cstring</>. to specify <quote>pseudotypes</> such as <type>cstring</>.
Pseudo-types indicate that the actual argument type is either Pseudotypes indicate that the actual argument type is either
incompletely specified, or outside the set of ordinary SQL data types. incompletely specified, or outside the set of ordinary SQL data types.
</para> </para>
</listitem> </listitem>
@ -92,15 +116,15 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
<listitem> <listitem>
<para> <para>
The return data type (optionally schema-qualified). The return type The return data type (optionally schema-qualified). The return type
may be specified as a base, complex, domain type may be specified as a base, complex, or domain type,
or the same as the type of an existing column. See the description or may copy the type of an existing column. See the description
under <literal>argtype</literal> above on how to reference the type under <literal>argtype</literal> above on how to reference the type
of an existing column. of an existing column.
</para> </para>
<para> <para>
Depending on the implementation language it may also be allowed Depending on the implementation language it may also be allowed
to specify <quote>pseudo-types</> such as <type>cstring</>. to specify <quote>pseudotypes</> such as <type>cstring</>.
The <literal>setof</literal> The <literal>SETOF</literal>
modifier indicates that the function will return a set of modifier indicates that the function will return a set of
items, rather than a single item. items, rather than a single item.
</para> </para>
@ -123,9 +147,9 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>IMMUTABLE</term> <term><literal>IMMUTABLE</literal></term>
<term>STABLE</term> <term><literal>STABLE</literal></term>
<term>VOLATILE</term> <term><literal>VOLATILE</literal></term>
<listitem> <listitem>
<para> <para>
@ -140,7 +164,7 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
<literal>IMMUTABLE</literal> indicates that the function always <literal>IMMUTABLE</literal> indicates that the function always
returns the same result when given the same argument values; that returns the same result when given the same argument values; that
is, it does not do database lookups or otherwise use information not 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 any call of the function with all-constant arguments can be
immediately replaced with the function value. immediately replaced with the function value.
</para> </para>
@ -152,7 +176,7 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
result could change across SQL statements. This is the appropriate result could change across SQL statements. This is the appropriate
selection for functions whose results depend on database lookups, selection for functions whose results depend on database lookups,
parameter variables (such as the current time zone), etc. Also note 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. as stable, since their values do not change within a transaction.
</para> </para>
@ -170,9 +194,9 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>CALLED ON NULL INPUT</term> <term><literal>CALLED ON NULL INPUT</literal></term>
<term>RETURNS NULL ON NULL INPUT</term> <term><literal>RETURNS NULL ON NULL INPUT</literal></term>
<term>STRICT</term> <term><literal>STRICT</literal></term>
<listitem> <listitem>
<para> <para>
@ -186,17 +210,17 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
<para> <para>
<literal>RETURNS NULL ON NULL INPUT</literal> or <literal>RETURNS NULL ON NULL INPUT</literal> or
<literal>STRICT</literal> indicates that the function always <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 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. automatically.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><optional>EXTERNAL</optional> SECURITY INVOKER</term> <term><literal><optional>EXTERNAL</optional> SECURITY INVOKER</literal></term>
<term><optional>EXTERNAL</optional> SECURITY DEFINER</term> <term><literal><optional>EXTERNAL</optional> SECURITY DEFINER</literal></term>
<listitem> <listitem>
<para> <para>
@ -209,7 +233,7 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
<para> <para>
The key word <literal>EXTERNAL</literal> is present for SQL 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. does not only apply to external functions.
</para> </para>
</listitem> </listitem>
@ -222,25 +246,26 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
<para> <para>
A string defining the function; the meaning depends on the A string defining the function; the meaning depends on the
language. It may be an internal function name, the path to an 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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<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> <listitem>
<para> <para>
This form of the <literal>AS</literal> clause is used for 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 in the C language source code is not the same as the name of
the SQL function. The string <replaceable the SQL function. The string <replaceable
class="parameter">obj_file</replaceable> is the name of the class="parameter">obj_file</replaceable> is the name of the
file containing the dynamically loadable object, and file containing the dynamically loadable object, and
<replaceable class="parameter">link_symbol</replaceable> is the <replaceable class="parameter">link_symbol</replaceable> is the
object's link symbol, that is, the name of the function in the C function's link symbol, that is, the name of the function in the C
language source code. 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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -285,48 +310,47 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
</refsect1> </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"> <refsect1 id="sql-createfunction-notes">
<title>Notes</title> <title>Notes</title>
<para> <para>
Refer to <xref linkend="xfunc"> for further information on writing Refer to <xref linkend="xfunc"> for further information on writing
external functions. functions.
</para> </para>
<para> <para>
The full <acronym>SQL</acronym> type syntax is allowed for The full <acronym>SQL</acronym> type syntax is allowed for
input arguments and return value. However, some details of the input arguments and return value. However, some details of the
type specification (e.g., the precision field for 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 underlying function implementation and are silently swallowed
(i.e., not recognized or (i.e., not recognized or
enforced) by the <command>CREATE FUNCTION</command> command. enforced) by the <command>CREATE FUNCTION</command> command.
</para> </para>
<para> <para>
<productname>PostgreSQL</productname> allows function <firstterm>overloading</firstterm>; <productname>PostgreSQL</productname> allows function
that is, the same name can be used for several different functions <firstterm>overloading</firstterm>; that is, the same name can be
so long as they have distinct argument types. This facility must used for several different functions so long as they have distinct
be used with caution for internal and C-language functions, however. argument types. However, the C names of all functions must be
</para> different, so you must give overloaded C functions different C
names (for example, use the argument types as part of the C
<para> names).
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.
</para> </para>
<para> <para>
@ -341,116 +365,26 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
to remove user-defined functions. to remove user-defined functions.
</para> </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> <para>
To be able to define a function, the user must have the To be able to define a function, the user must have the
<literal>USAGE</literal> privilege on the language. <literal>USAGE</literal> privilege on the language.
</para> </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>
<refsect1 id="sql-createfunction-examples"> <refsect1 id="sql-createfunction-examples">
<title>Examples</title> <title>Examples</title>
<para> <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> <programlisting>
CREATE FUNCTION one() RETURNS integer CREATE FUNCTION add(integer, integer) RETURNS integer
AS 'SELECT 1 AS RESULT;' AS 'select $1 + $2;'
LANGUAGE SQL; LANGUAGE SQL
IMMUTABLE
SELECT one() AS answer; RETURNS NULL ON NULL INPUT;
<computeroutput>
answer
--------
1
</computeroutput>
</programlisting> </programlisting>
</para> </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> </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 PostgreSQL documentation
--> -->
@ -8,35 +8,41 @@ PostgreSQL documentation
<refentrytitle id="sql-creategroup-title">CREATE GROUP</refentrytitle> <refentrytitle id="sql-creategroup-title">CREATE GROUP</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>CREATE GROUP</refname>
CREATE GROUP <refpurpose>define a new user group</refpurpose>
</refname>
<refpurpose>
define a new user group
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>2000-01-14</date>
</refsynopsisdivinfo>
<synopsis>
CREATE GROUP <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ] ] CREATE GROUP <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ] ]
where <replaceable class="PARAMETER">option</replaceable> can be: where <replaceable class="PARAMETER">option</replaceable> can be:
SYSID <replaceable class="PARAMETER">gid</replaceable> SYSID <replaceable class="PARAMETER">gid</replaceable>
| USER <replaceable class="PARAMETER">username</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"> <refsect1>
<refsect2info> <title>Parameters</title>
<date>2000-01-14</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
@ -53,11 +59,11 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
<listitem> <listitem>
<para> <para>
The <literal>SYSID</literal> clause can be used to choose 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. group. It is not necessary to do so, however.
</para> </para>
<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. starting at 1, will be used as default.
</para> </para>
</listitem> </listitem>
@ -73,54 +79,26 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para> </refsect1>
</refsect2>
<refsect2 id="R2-SQL-CREATEGROUP-2"> <refsect1>
<refsect2info> <title>Diagnostics</title>
<date>2000-01-14</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><computeroutput>CREATE GROUP</computeroutput></term> <term><computeroutput>CREATE GROUP</computeroutput></term>
<listitem> <listitem>
<para> <para>
Message returned if the command completes successfully. Message returned if the group was successfully created.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para> </refsect1>
</refsect2>
</refsynopsisdiv> <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> <para>
Create an empty group: Create an empty group:
<programlisting> <programlisting>
@ -136,24 +114,13 @@ CREATE GROUP marketing WITH USER jonathan, david;
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-CREATEGROUP-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-CREATEGROUP-4"> <para>
<refsect2info> There is no <command>CREATE GROUP</command> statement in the SQL
<date>2000-01-14</date> standard. Roles are similar in concept to groups.
</refsect2info> </para>
<title>
SQL92
</title>
<para>
There is no <command>CREATE GROUP</command> statement in SQL92.
Roles are similar in concept to groups.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </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 PostgreSQL documentation
--> -->
@ -8,39 +8,101 @@ PostgreSQL documentation
<refentrytitle id="sql-createindex-title">CREATE INDEX</refentrytitle> <refentrytitle id="sql-createindex-title">CREATE INDEX</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </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"> <refnamediv>
<refsect2info> <refname>CREATE INDEX</refname>
<date>1998-09-09</date> <refpurpose>define a new index</refpurpose>
</refsect2info> </refnamediv>
<title>
Inputs <refsynopsisdiv>
</title> <synopsis>
<para> 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> <variablelist>
<varlistentry> <varlistentry>
<term>UNIQUE</term> <term><literal>UNIQUE</literal></term>
<listitem> <listitem>
<para> <para>
Causes the system to check for Causes the system to check for
@ -73,52 +135,13 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><replaceable class="parameter">acc_method</replaceable></term> <term><replaceable class="parameter">method</replaceable></term>
<listitem> <listitem>
<para> <para>
The name of the access method to be used for the index. The The name of the method to be used for the index. Choices are
default access method is <literal>BTREE</literal>. <literal>btree</literal>, <literal>hash</literal>,
<application>PostgreSQL</application> provides four access <literal>rtree</literal>, and <literal>gist</literal>. The
methods for indexes: default method is <literal>btree</literal>.
<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>
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -159,249 +182,73 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para> </refsect1>
</refsect2>
<refsect2 id="R2-SQL-CREATEINDEX-2"> <refsect1>
<refsect2info> <title>Diagnostics</title>
<date>1998-09-09</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><computeroutput> <term><computeroutput>CREATE INDEX</computeroutput></term>
CREATE INDEX <listitem>
</computeroutput></term> <para>
<listitem> Message returned if the index was successfully created.
<para> </para>
The message returned if the index is successfully created. </listitem>
</para> </varlistentry>
</listitem> </variablelist>
</varlistentry> </refsect1>
<varlistentry> <refsect1>
<term><computeroutput> <title>Notes</title>
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 id="R1-SQL-CREATEINDEX-1">
<refsect1info>
<date>1998-09-09</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>CREATE INDEX</command> constructs an index See <xref linkend="indexes"> for information about when indexes can
<replaceable class="parameter">index_name</replaceable> be used, when they are not used, and in which particular situations
on the specified <replaceable class="parameter">table</replaceable>. can be useful.
<tip>
<para>
Indexes are primarily used to enhance database performance.
But inappropriate use will result in slower performance.
</para>
</tip>
</para> </para>
<para> <para>
In the first syntax shown above, the key field(s) for the Currently, only the B-tree and GiST index methods support
index are specified as column names. multicolumn indexes. Up to 32 fields may be specified by default.
Multiple fields can be specified if the index access method supports (This limit can be altered when building
multicolumn indexes. <application>PostgreSQL</application>.) Only B-tree currently
supports unique indexes.
</para> </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> <para>
An <firstterm>operator class</firstterm> can be specified for each An <firstterm>operator class</firstterm> can be specified for each
column of an index. The operator class identifies the operators to be 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 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; four-byte integers would use the <literal>int4_ops</literal> class;
this operator class includes comparison functions for four-byte 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 type is usually sufficient. The main point of having operator classes
is that for some data types, there could be more than one meaningful 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 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 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 defining two operator classes for the data type and then selecting
the proper class when making an index. There are also some operator the proper class when making an index. More information about
classes with special purposes: operator classes is in <xref linkend="indexes-opclass"> and in <xref
linkend="xindex">.
<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>
</para> </para>
<para> <para>
The following query shows all defined operator classes: Use <xref linkend="sql-dropindex" endterm="sql-dropindex-title">
to remove an index.
<programlisting> </para>
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>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-CREATEINDEX-2"> <refsect1>
<title> <title>Examples</title>
Usage
</title> <para>
<para>To create a B-tree index on the field <literal>title</literal> To create a B-tree index on the column <literal>title</literal> in
in the table <literal>films</literal>: the table <literal>films</literal>:
<programlisting>
CREATE UNIQUE INDEX title_idx ON films (title);
</programlisting>
</para> </para>
<programlisting>
CREATE UNIQUE INDEX title_idx
ON films (title);
</programlisting>
<!-- <!--
<comment> <comment>
@ -422,25 +269,14 @@ SELECT * FROM points
</refsect1> </refsect1>
<refsect1 id="R1-SQL-CREATEINDEX-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title> <para>
<command>CREATE INDEX</command> is a
<refsect2 id="R2-SQL-CREATEINDEX-4"> <productname>PostgreSQL</productname> language extension. There
<refsect2info> are no provisions for indexes in the SQL standard.
<date>1998-09-09</date> </para>
</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> </refsect1>
</refentry> </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 PostgreSQL documentation
--> -->
@ -60,7 +60,7 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">langna
<literal>TRUSTED</literal> specifies that the call handler for <literal>TRUSTED</literal> specifies that the call handler for
the language is safe, that is, it does not offer an the language is safe, that is, it does not offer an
unprivileged user any functionality to bypass access 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 language, only users with the
<productname>PostgreSQL</productname> superuser privilege can <productname>PostgreSQL</productname> superuser privilege can
use this language to create new functions. use this language to create new functions.
@ -84,8 +84,8 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">langna
<listitem> <listitem>
<para> <para>
The name of the new procedural language. The language name is The name of the new procedural language. The language name is
case insensitive. A procedural language cannot override one of case insensitive. The name must be unique among the languages
the built-in languages of <productname>PostgreSQL</productname>. in the database.
</para> </para>
<para> <para>
@ -146,45 +146,16 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">langna
<refsect1 id="sql-createlanguage-diagnostics"> <refsect1 id="sql-createlanguage-diagnostics">
<title>Diagnostics</title> <title>Diagnostics</title>
<msgset> <variablelist>
<msgentry> <varlistentry>
<msg> <term><computeroutput>CREATE LANGUAGE</computeroutput></term>
<msgmain> <listitem>
<msgtext>
<screen>
CREATE LANGUAGE
</screen>
</msgtext>
</msgmain>
</msg>
<msgexplan>
<para> <para>
This message is returned if the language is successfully Message returned if the language was successfully created.
created.
</para> </para>
</msgexplan> </listitem>
</msgentry> </varlistentry>
</variablelist>
<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>
</refsect1> </refsect1>
<refsect1 id="sql-createlanguage-notes"> <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. This command normally should not be executed directly by users.
For the procedural languages supplied in the For the procedural languages supplied in the
<productname>PostgreSQL</productname> distribution, the <xref <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> install the correct call handler. (<command>createlang</command>
will call <command>CREATE LANGUAGE</command> internally.) will call <command>CREATE LANGUAGE</command> internally.)
</para> </para>
@ -205,7 +176,7 @@ ERROR: PL handler function <replaceable class="parameter">funcname</replaceable
type <type>opaque</>, rather than <type>language_handler</>. type <type>opaque</>, rather than <type>language_handler</>.
To support loading To support loading
of old dump files, <command>CREATE LANGUAGE</> will accept a function 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</>. change the function's declared return type to <type>language_handler</>.
</para> </para>
@ -216,35 +187,19 @@ ERROR: PL handler function <replaceable class="parameter">funcname</replaceable
<para> <para>
Use <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">, or better yet the <xref 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>
<para> <para>
The system catalog <classname>pg_language</classname> records The system catalog <classname>pg_language</classname> (see <xref
information about the currently installed procedural languages. linkend="catalog-pg-language">) records information about the
currently installed languages. Also <command>createlang</command>
<screen> has an option to list the installed languages.
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>
</para> </para>
<para> <para>
At present, with the exception of the permissions, the definition The definition of a procedural language cannot be changed once it
of a procedural language cannot be changed once it has been created. has been created, with the exception of the privileges.
</para> </para>
<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 The following two commands executed in sequence will register a new
procedural language and the associated call handler. procedural language and the associated call handler.
<programlisting> <programlisting>
CREATE FUNCTION plsample_call_handler () RETURNS language_handler CREATE FUNCTION plsample_call_handler() RETURNS language_handler
AS '$libdir/plsample' AS '$libdir/plsample'
LANGUAGE C; LANGUAGE C;
CREATE LANGUAGE plsample CREATE LANGUAGE plsample
@ -280,15 +235,6 @@ CREATE LANGUAGE plsample
</para> </para>
</refsect1> </refsect1>
<refsect1>
<title>History</title>
<para>
The <command>CREATE LANGUAGE</command> command first appeared in
<productname>PostgreSQL</productname> 6.3.
</para>
</refsect1>
<refsect1> <refsect1>
<title>See Also</title> <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 PostgreSQL documentation
--> -->
@ -8,206 +8,44 @@ PostgreSQL documentation
<refentrytitle id="sql-createopclass-title">CREATE OPERATOR CLASS</refentrytitle> <refentrytitle id="sql-createopclass-title">CREATE OPERATOR CLASS</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>CREATE OPERATOR CLASS</refname>
CREATE OPERATOR CLASS <refpurpose>define a new operator class for indexes</refpurpose>
</refname> </refnamediv>
<refpurpose>
define a new operator class for indexes
</refpurpose>
</refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>2002-07-28</date> 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
</refsynopsisdivinfo> { 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 ]
<synopsis> | FUNCTION <replaceable class="parameter">support_number</replaceable> <replaceable class="parameter">func_name</replaceable> ( <replaceable class="parameter">argument_types</replaceable> )
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> )
| STORAGE <replaceable class="parameter">storage_type</replaceable> | STORAGE <replaceable class="parameter">storage_type</replaceable>
} [, ... ] } [, ... ]
</synopsis> </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>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-CREATEOPCLASS-1"> <refsect1>
<refsect1info> <title>Description</title>
<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>
<para> <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 operator class defines how a particular data type can be used with
an index. The operator class specifies that certain operators will fill an index. The operator class specifies that certain operators will fill
particular roles or <quote>strategies</> for this data type and this 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 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 index column. All the operators and functions used by an operator
class must be defined before the operator class is created. class must be defined before the operator class is created.
</para> </para>
<para> <para>
If a schema name is given then the operator class is created in the 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 specified schema. Otherwise it is created in the current schema.
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
Two operator classes in the same schema can have the same name only if they 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>
<para> <para>
The user who defines an operator class becomes its owner. Presently, The user who defines an operator class becomes its owner. Presently,
the creating user must be a superuser. (This restriction is made because the creating user must be a superuser. (This restriction is made because
@ -217,41 +55,187 @@ CREATE OPERATOR CLASS
<para> <para>
<command>CREATE OPERATOR CLASS</command> does not presently check <command>CREATE OPERATOR CLASS</command> does not presently check
whether the class definition includes all the operators and functions whether the operator class definition includes all the operators and functions
required by the index access method. It is the user's required by the index method. It is the user's
responsibility to define a valid operator class. responsibility to define a valid operator class.
</para> </para>
<para> <para>
Refer to <xref linkend="xindex"> for further information. Refer to <xref linkend="xindex"> for further information.
</para> </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>
<refsect1 id="R1-SQL-CREATEOPCLASS-2"> <refsect1>
<title> <title>Parameters</title>
Usage
</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> <para>
The following example command defines a GiST index operator class 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. <filename>contrib/intarray/</> for the complete example.
</para> </para>
<programlisting> <programlisting>
CREATE OPERATOR CLASS gist__int_ops CREATE OPERATOR CLASS gist__int_ops
DEFAULT FOR TYPE _int4 USING gist AS DEFAULT FOR TYPE _int4 USING gist AS
OPERATOR 3 &&, OPERATOR 3 &&,
@ -266,34 +250,18 @@ CREATE OPERATOR CLASS gist__int_ops
FUNCTION 5 g_int_penalty (internal, internal, internal), FUNCTION 5 g_int_penalty (internal, internal, internal),
FUNCTION 6 g_int_picksplit (internal, internal), FUNCTION 6 g_int_picksplit (internal, internal),
FUNCTION 7 g_int_same (_int4, _int4, internal); FUNCTION 7 g_int_same (_int4, _int4, internal);
</programlisting> </programlisting>
<para>
The <literal>OPERATOR</>, <literal>FUNCTION</>, and <literal>STORAGE</>
clauses may appear in any order.
</para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-CREATEOPCLASS-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-CREATEOPCLASS-4">
<refsect2info>
<date>2002-07-28</date>
</refsect2info>
<title>
SQL92
</title>
<para> <para>
<command>CREATE OPERATOR CLASS</command> <command>CREATE OPERATOR CLASS</command> is a
is a <productname>PostgreSQL</productname> extension. <productname>PostgreSQL</productname> extension. There is no
There is no <command>CREATE OPERATOR CLASS</command> <command>CREATE OPERATOR CLASS</command> statement in the SQL
statement in <acronym>SQL92</acronym>. standard.
</para> </para>
</refsect2>
</refsect1> </refsect1>
</refentry> </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 PostgreSQL documentation
--> -->
@ -8,218 +8,43 @@ PostgreSQL documentation
<refentrytitle id="sql-createoperator-title">CREATE OPERATOR</refentrytitle> <refentrytitle id="sql-createoperator-title">CREATE OPERATOR</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>CREATE OPERATOR</refname>
CREATE OPERATOR <refpurpose>define a new operator</refpurpose>
</refname> </refnamediv>
<refpurpose>
define a new operator
</refpurpose>
</refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>2000-03-25</date> CREATE OPERATOR <replaceable>name</replaceable> (
</refsynopsisdivinfo> PROCEDURE = <replaceable class="parameter">func_name</replaceable>
<synopsis> [, LEFTARG = <replaceable class="parameter">lefttype</replaceable> ] [, RIGHTARG = <replaceable class="parameter">righttype</replaceable> ]
CREATE OPERATOR <replaceable>name</replaceable> ( PROCEDURE = <replaceable class="parameter">func_name</replaceable> [, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ] [, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ]
[, LEFTARG = <replaceable class="parameter">lefttype</replaceable> [, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ] [, JOIN = <replaceable class="parameter">join_proc</replaceable> ]
] [, RIGHTARG = <replaceable class="parameter">righttype</replaceable> ] [, HASHES ] [, MERGES ]
[, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ] [, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ] [, SORT1 = <replaceable class="parameter">left_sort_op</replaceable> ] [, SORT2 = <replaceable class="parameter">right_sort_op</replaceable> ]
[, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ] [, JOIN = <replaceable class="parameter">join_proc</replaceable> ] [, LTCMP = <replaceable class="parameter">less_than_op</replaceable> ] [, GTCMP = <replaceable class="parameter">greater_than_op</replaceable> ]
[, HASHES ] [, MERGES ] )
[, SORT1 = <replaceable class="parameter">left_sort_op</replaceable> ] [, SORT2 = <replaceable class="parameter">right_sort_op</replaceable> ] </synopsis>
[, 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>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-CREATEOPERATOR-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>2000-03-25</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>CREATE OPERATOR</command> defines a new operator, <command>CREATE OPERATOR</command> defines a new operator,
<replaceable class="parameter">name</replaceable>. <replaceable class="parameter">name</replaceable>. The user who
The user who defines an operator becomes its owner. defines an operator becomes its owner. If a schema name is given
</para> then the operator is created in the specified schema. Otherwise it
<para> is created in the current schema.
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.
</para> </para>
<para> <para>
The operator <replaceable class="parameter">name</replaceable> The operator name is a sequence of up to <symbol>NAMEDATALEN</>-1
is a sequence of up to <symbol>NAMEDATALEN</>-1 (63 by default) characters (63 by default) characters from the following list:
from the following list: <literallayout>
<literallayout>
+ - * / &lt; &gt; = ~ ! @ # % ^ &amp; | ` ? $ + - * / &lt; &gt; = ~ ! @ # % ^ &amp; | ` ? $
</literallayout> </literallayout>
There are a few restrictions on your choice of name: There are a few restrictions on your choice of name:
<itemizedlist> <itemizedlist>
@ -240,263 +65,258 @@ CREATE OPERATOR
A multicharacter operator name cannot end in <literal>+</literal> or A multicharacter operator name cannot end in <literal>+</literal> or
<literal>-</literal>, <literal>-</literal>,
unless the name also contains at least one of these characters: unless the name also contains at least one of these characters:
<literallayout> <literallayout>
~ ! @ # % ^ &amp; | ` ? $ ~ ! @ # % ^ &amp; | ` ? $
</literallayout> </literallayout>
For example, <literal>@-</literal> is an allowed operator name, For example, <literal>@-</literal> is an allowed operator name,
but <literal>*-</literal> is not. but <literal>*-</literal> is not.
This restriction allows <productname>PostgreSQL</productname> to 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> </para>
</listitem> </listitem>
</itemizedlist> </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> <para>
The operator <literal>!=</literal> is mapped to <literal>&lt;&gt;</literal> on input, so these two names The operator <literal>!=</literal> is mapped to
are always equivalent. <literal>&lt;&gt;</literal> on input, so these two names are always
equivalent.
</para> </para>
<para> <para>
At least one of <literal>LEFTARG</> and <literal>RIGHTARG</> must be defined. For At least one of <literal>LEFTARG</> and <literal>RIGHTARG</> must be defined. For
binary operators, both should be defined. For right unary binary operators, both must be defined. For right unary
operators, only <literal>LEFTARG</> should be defined, while for left operators, only <literal>LEFTARG</> should be defined, while for left
unary operators only <literal>RIGHTARG</> should be defined. unary operators only <literal>RIGHTARG</> should be defined.
</para> </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> <para>
box '((0,0), (1,1))' &gt;&gt;&gt; MYBOXES.description The <replaceable class="parameter">func_name</replaceable>
</programlisting> 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> <para>
This allows the execution code to always use the latter To give a schema-qualified operator name in <replaceable
representation and simplifies the query optimizer somewhat. class="parameter">com_op</replaceable> or the other optional
</para> arguments, use the <literal>OPERATOR()</> syntax, for example
<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:
<programlisting> <programlisting>
myboxes.description &lt;&lt;&lt; box '((0,0), (1,1))' COMMUTATOR = OPERATOR(myschema.===) ,
</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.===) ,
</programlisting> </programlisting>
</para> </para>
</refsect2> </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>
<refsect1 id="R1-SQL-CREATEOPERATOR-2"> <refsect1>
<title> <title>Notes</title>
Usage
</title> <para>
<para>The following command defines a new operator, Refer to <xref linkend="xoper"> for further information.
area-equality, for the BOX data type:
</para> </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 === ( CREATE OPERATOR === (
LEFTARG = box, LEFTARG = box,
RIGHTARG = box, RIGHTARG = box,
PROCEDURE = area_equal_procedure, PROCEDURE = area_equal_procedure,
COMMUTATOR = ===, COMMUTATOR = ===,
NEGATOR = !==, NEGATOR = !==,
RESTRICT = area_restriction_procedure, RESTRICT = area_restriction_procedure,
JOIN = area_join_procedure, JOIN = area_join_procedure,
HASHES, HASHES,
SORT1 = &lt;&lt;&lt;, SORT1 = &lt;&lt;&lt;,
SORT2 = &lt;&lt;&lt; SORT2 = &lt;&lt;&lt;
-- Since sort operators were given, MERGES is implied. -- Since sort operators were given, MERGES is implied.
-- LTCMP and GTCMP are assumed to be &lt; and &gt; respectively -- LTCMP and GTCMP are assumed to be &lt; and &gt; respectively
); );
</programlisting> </programlisting>
</para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-CREATEOPERATOR-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-CREATEOPERATOR-4">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>
<title>
SQL92
</title>
<para> <para>
<command>CREATE OPERATOR</command> <command>CREATE OPERATOR</command> is a
is a <productname>PostgreSQL</productname> extension. <productname>PostgreSQL</productname> extension. There are no
There is no <command>CREATE OPERATOR</command> provisions for user-defined operators in the SQL standard.
statement in <acronym>SQL92</acronym>. </para>
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </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 PostgreSQL documentation
--> -->
@ -8,138 +8,22 @@ PostgreSQL documentation
<refentrytitle id="sql-createrule-title">CREATE RULE</refentrytitle> <refentrytitle id="sql-createrule-title">CREATE RULE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>CREATE RULE</refname>
CREATE RULE <refpurpose>define a new rewrite rule</refpurpose>
</refname>
<refpurpose>
define a new rewrite rule
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>2001-01-05</date>
</refsynopsisdivinfo>
<synopsis>
CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS ON <replaceable class="parameter">event</replaceable> 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> ] TO <replaceable class="parameter">table</replaceable> [ WHERE <replaceable class="parameter">condition</replaceable> ]
DO [ INSTEAD ] <replaceable class="parameter">action</replaceable> DO [ INSTEAD ] { NOTHING | <replaceable class="parameter">command</replaceable> | ( <replaceable class="parameter">command</replaceable> ; <replaceable class="parameter">command</replaceable> ... ) }
</synopsis>
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>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-CREATERULE-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-09-11</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>CREATE RULE</command> defines a new rule applying to a specified <command>CREATE RULE</command> defines a new rule applying to a specified
@ -150,186 +34,206 @@ CREATE RULE
</para> </para>
<para> <para>
The <productname>PostgreSQL</productname> The <productname>PostgreSQL</productname> rule system allows one to
<firstterm>rule system</firstterm> allows one to define an define an alternate action to be performed on insertions, updates,
alternate action to be performed on inserts, updates, or deletions or deletions in database tables. Roughly speaking, a rule causes
from database tables. Rules are used to additional commands to be executed when a given command on a given
implement table views as well. table is executed. Alternatively, a rule can replace a given
</para> 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
<para> to realize that a rule is really a command transformation
The semantics of a rule is that at the time an individual instance (row) mechanism, or command macro. The transformation happens before the
is execution of the commands starts. If you actually want an
accessed, inserted, updated, or deleted, there is an old instance (for operation that fires independently for each physical row, you
selects, updates and deletes) and a new instance (for inserts and probably want to use a trigger, not a rule. More information about
updates). All the rules for the given event type and the given target the rules system is in <xref linkend="rules">.
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.
</para> </para>
<refsect2 id="R2-SQL-CREATERULE-3"> <para>
<refsect2info> Presently, <literal>ON SELECT</literal> rules must be unconditional
<date>2001-11-06</date> <literal>INSTEAD</literal> rules and must have actions that consist
</refsect2info> of a single <command>SELECT</command> command. Thus, an
<title> <literal>ON SELECT</literal> rule effectively turns the table into
Rules and Views a view, whose visible contents are the rows returned by the rule's
</title> <command>SELECT</command> command rather than whatever had been
<para> stored in the table (if anything). It is considered better style
Presently, ON SELECT rules must be unconditional INSTEAD rules and must to write a <command>CREATE VIEW</command> command than to create a
have actions that consist of a single SELECT query. Thus, an ON SELECT real table and define an <literal>ON SELECT</literal> rule for it.
rule effectively turns the table into a view, whose visible </para>
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> <para>
<xref linkend="sql-createview" endterm="sql-createview-title"> creates a dummy table (with no underlying You can create the illusion of an updatable view by defining
storage) and associates an ON SELECT rule with it. The system will not <literal>ON INSERT</literal>, <literal>ON UPDATE</literal>, and
allow updates to the view, since it knows there is no real table there. <literal>ON DELETE</literal> rules (or any subset of those that's
You can create the sufficient for your purposes) to replace update actions on the view
illusion of an updatable view by defining ON INSERT, ON UPDATE, and with appropriate updates on other tables.
ON DELETE rules (or any subset of those that's sufficient </para>
for your purposes) to replace update actions on the view with
appropriate updates on other tables.
</para>
<para> <para>
There is a catch if you try to use conditional There is a catch if you try to use conditional rules for view
rules for view updates: there <emphasis>must</> be an unconditional updates: there <emphasis>must</> be an unconditional
INSTEAD rule for each action you wish to allow on the view. If the <literal>INSTEAD</literal> rule for each action you wish to allow
rule is conditional, or is not INSTEAD, then the system will still reject on the view. If the rule is conditional, or is not
attempts to perform the update action, because it thinks it might end up <literal>INSTEAD</literal>, then the system will still reject
trying to perform the action on the dummy table in some cases. attempts to perform the update action, because it thinks it might
If you want to end up trying to perform the action on the dummy table of the view
handle all the useful cases in conditional rules, you can; just add an in some cases. If you want to handle all the useful cases in
unconditional DO INSTEAD NOTHING rule to ensure that the system conditional rules, you can; just add an unconditional <literal>DO
understands it will never be called on to update the dummy table. Then INSTEAD NOTHING</literal> rule to ensure that the system
make the conditional rules non-INSTEAD; in the cases where they fire, understands it will never be called on to update the dummy table.
they add to the default INSTEAD NOTHING action. Then make the conditional rules not <literal>INSTEAD</literal>; in
</para> the cases where they are applied, they add to the default
</refsect2> <literal>INSTEAD NOTHING</literal> action.
</para>
</refsect1>
<refsect2 id="R2-SQL-CREATERULE-4"> <refsect1>
<refsect2info> <title>Parameters</title>
<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>
<para> <variablelist>
It is very important to take care to avoid circular rules. <varlistentry>
For example, though each <term><replaceable class="parameter">name</replaceable></term>
of the following two rule definitions are accepted by <listitem>
<productname>PostgreSQL</productname>, the <para>
select command will cause <productname>PostgreSQL</productname> to The name of a rule to create. This must be distinct from the
report an error because the query cycled too many times: 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> <programlisting>
CREATE RULE "_RETURN" AS CREATE RULE "_RETURN" AS
ON SELECT TO emp ON SELECT TO t1
DO INSTEAD DO INSTEAD
SELECT * FROM toyemp; SELECT * FROM t2;
CREATE RULE "_RETURN" AS CREATE RULE "_RETURN" AS
ON SELECT TO toyemp ON SELECT TO t2
DO INSTEAD DO INSTEAD
SELECT * FROM emp; SELECT * FROM t1;
SELECT * FROM t1;
</programlisting> </programlisting>
</para>
This attempt to select from <literal>EMP</literal> will cause <para>
<productname>PostgreSQL</productname> to issue an error Presently, if a rule action contains a <command>NOTIFY</command>
because the queries cycled too many times: command, the <command>NOTIFY</command> command will be executed
unconditionally, that is, the <command>NOTIFY</command> will be
<programlisting> issued even if there are not any rows that the rule should apply
SELECT * FROM emp; to. For example, in
</programlisting> <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>
CREATE RULE notify_me AS ON UPDATE TO mytable DO NOTIFY mytable; CREATE RULE notify_me AS ON UPDATE TO mytable DO NOTIFY mytable;
UPDATE mytable SET name = 'foo' WHERE id = 42; UPDATE mytable SET name = 'foo' WHERE id = 42;
</programlisting> </programlisting>
one NOTIFY event will be sent during the UPDATE, whether or not there one <command>NOTIFY</command> event will be sent during the
are any rows with id = 42. This is an implementation restriction that <command>UPDATE</command>, whether or not there are any rows with
may be fixed in future releases. <literal>id = 42</literal>. This is an implementation restriction
</para> that may be fixed in future releases.
</refsect2> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-CREATERULE-4"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-CREATERULE-5"> <para>
<refsect2info> <command>CREATE RULE</command> is a
<date>1998-09-11</date> <productname>PostgreSQL</productname> language extension, as is the
</refsect2info> entire rules system.
<title> </para>
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>
</refsect1> </refsect1>
</refentry> </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 PostgreSQL documentation
--> -->
@ -8,25 +8,51 @@ PostgreSQL documentation
<refentrytitle id="sql-createschema-title">CREATE SCHEMA</refentrytitle> <refentrytitle id="sql-createschema-title">CREATE SCHEMA</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>CREATE SCHEMA</refname>
CREATE SCHEMA <refpurpose>define a new schema</refpurpose>
</refname>
<refpurpose>
define a new schema
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
CREATE SCHEMA <replaceable class="parameter">schemaname</replaceable> [ AUTHORIZATION <replaceable class="parameter">username</replaceable> ] [ <replaceable class="parameter">schema_element</replaceable> [ ... ] ] 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> [ ... ] ] 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"> <refsect1>
<title> <title>Parameters</title>
Inputs
</title>
<para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
@ -63,164 +89,112 @@ CREATE SCHEMA AUTHORIZATION <replaceable class="parameter">username</replaceable
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </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>
<refsect1 id="R1-SQL-CREATESCHEMA-2"> <refsect1>
<title> <title>Diagnostics</title>
Examples
</title>
<para>
Create a schema:
<programlisting> <variablelist>
CREATE SCHEMA myschema; <varlistentry>
</programlisting> <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>
<para> <para>
Create a schema for user <literal>joe</> --- the schema will also Use <command>DROP SCHEMA</command> to remove a schema.
be named <literal>joe</>: </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; CREATE SCHEMA AUTHORIZATION joe;
</programlisting> </programlisting>
</para> </para>
<para> <para>
Create a schema and create a table and view within it: Create a schema and create a table and view within it:
<programlisting>
<programlisting>
CREATE SCHEMA hollywood CREATE SCHEMA hollywood
CREATE TABLE films (title text, release date, awards text[]) CREATE TABLE films (title text, release date, awards text[])
CREATE VIEW winners AS CREATE VIEW winners AS
SELECT title, release FROM films WHERE awards IS NOT NULL; SELECT title, release FROM films WHERE awards IS NOT NULL;
</programlisting> </programlisting>
Notice that the individual subcommands do not end with semicolons. Notice that the individual subcommands do not end with semicolons.
</para> </para>
<para> <para>
The following is an equivalent way of accomplishing the same result: The following is an equivalent way of accomplishing the same result:
<programlisting> <programlisting>
CREATE SCHEMA hollywood; CREATE SCHEMA hollywood;
CREATE TABLE hollywood.films (title text, release date, awards text[]); CREATE TABLE hollywood.films (title text, release date, awards text[]);
CREATE VIEW hollywood.winners AS CREATE VIEW hollywood.winners AS
SELECT title, release FROM hollywood.films WHERE awards IS NOT NULL; SELECT title, release FROM hollywood.films WHERE awards IS NOT NULL;
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-CREATESCHEMA-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-CREATESCHEMA-4"> <para>
<title> The SQL standard allows a <literal>DEFAULT CHARACTER SET</> clause
SQL92 in <command>CREATE SCHEMA</command>, as well as more subcommand
</title> types than are presently accepted by
<productname>PostgreSQL</productname>.
</para>
<para> <para>
SQL92 allows a <literal>DEFAULT CHARACTER SET</> clause in The SQL standard specifies that the subcommands in <command>CREATE
<command>CREATE SCHEMA</command>, as well as more subcommand types SCHEMA</command> may appear in any order. The present
than are presently accepted by <productname>PostgreSQL</productname>. <productname>PostgreSQL</productname> implementation does not
</para> handle all cases of forward references in subcommands; it may
sometimes be necessary to reorder the subcommands to avoid forward
references.
</para>
<para> <para>
SQL92 specifies that the subcommands in <command>CREATE SCHEMA</command> According to the SQL standard, the owner of a schema always owns
may appear in any order. The present all objects within it. <productname>PostgreSQL</productname>
<productname>PostgreSQL</productname> implementation does not handle all allows schemas to contain objects owned by users other than the
cases of forward references in subcommands; it may sometimes be necessary schema owner. This can happen only if the schema owner grants the
to reorder the subcommands to avoid forward references. <literal>CREATE</> privilege on his schema to someone else.
</para> </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>
</refsect1> </refsect1>
</refentry> </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 PostgreSQL documentation
--> -->
@ -8,248 +8,36 @@ PostgreSQL documentation
<refentrytitle id="sql-createsequence-title">CREATE SEQUENCE</refentrytitle> <refentrytitle id="sql-createsequence-title">CREATE SEQUENCE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>CREATE SEQUENCE</refname>
CREATE SEQUENCE <refpurpose>define a new sequence generator</refpurpose>
</refname>
<refpurpose>
define a new sequence generator
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
CREATE [ TEMPORARY | TEMP ] SEQUENCE <replaceable class="parameter">seqname</replaceable> [ INCREMENT [ BY ] <replaceable class="parameter">increment</replaceable> ] 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 ] [ 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 ] [ START [ WITH ] <replaceable class="parameter">start</replaceable> ] [ CACHE <replaceable class="parameter">cache</replaceable> ] [ [ NO ] CYCLE ]
</synopsis> </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>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-CREATESEQUENCE-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-09-11</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>CREATE SEQUENCE</command> will enter a new sequence number generator <command>CREATE SEQUENCE</command> creates a new sequence number
into the current database. This involves creating and initializing a generator. This involves creating and initializing a new special
new single-row single-row table with the name <replaceable
table with the name <replaceable class="parameter">seqname</replaceable>. class="parameter">seqname</replaceable>. The generator will be
The generator will be owned by the user issuing the command. owned by the user issuing the command.
</para> </para>
<para> <para>
If a schema name is given then the sequence is created in the 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 specified schema. Otherwise it is created in the current schema.
at the front of the search path; see <literal>CURRENT_SCHEMA()</>). Temporary sequences exist in a special schema, so a schema name may not be
TEMP sequences exist in a special schema, so a schema name may not be given when creating a temporary sequence.
given when creating a TEMP sequence.
The sequence name must be distinct from the name of any other sequence, The sequence name must be distinct from the name of any other sequence,
table, index, or view in the same schema. table, index, or view in the same schema.
</para> </para>
@ -257,7 +45,7 @@ ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceabl
<para> <para>
After a sequence is created, you use the functions After a sequence is created, you use the functions
<function>nextval</function>, <function>nextval</function>,
<function>currval</function> and <function>currval</function>, and
<function>setval</function> <function>setval</function>
to operate on the sequence. These functions are documented in to operate on the sequence. These functions are documented in
<xref linkend="functions-sequence">. <xref linkend="functions-sequence">.
@ -266,132 +54,293 @@ ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceabl
<para> <para>
Although you cannot update a sequence directly, you can use a query like Although you cannot update a sequence directly, you can use a query like
<programlisting> <programlisting>
SELECT * FROM <replaceable>seqname</replaceable>; SELECT * FROM <replaceable>seqname</replaceable>;
</programlisting> </programlisting>
to examine the parameters and current state of a sequence. In particular, to examine the parameters and current state of a sequence. In particular,
the <literal>last_value</> field of the sequence shows the last value the <literal>last_value</> field of the sequence shows the last value
allocated by any backend process. (Of course, this value may be obsolete allocated by any session. (Of course, this value may be obsolete
by the time it's printed, if other processes are actively doing by the time it's printed, if other sessions are actively doing
<function>nextval</> calls.) <function>nextval</> calls.)
</para> </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>
<refsect1 id="R1-SQL-CREATESEQUENCE-2"> <refsect1>
<title> <title>Parameters</title>
Usage
</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> <para>
Create an ascending sequence called <literal>serial</literal>, starting at 101: Create an ascending sequence called <literal>serial</literal>, starting at 101:
</para> <programlisting>
<programlisting>
CREATE SEQUENCE serial START 101; CREATE SEQUENCE serial START 101;
</programlisting> </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>
</para> </para>
<para> <para>
Update the sequence value after a COPY FROM: Select the next number from this sequence:
<programlisting> <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; BEGIN;
COPY distributors FROM 'input_file'; COPY distributors FROM 'input_file';
SELECT setval('serial', max(id)) FROM distributors; SELECT setval('serial', max(id)) FROM distributors;
END; END;
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-CREATESEQUENCE-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-CREATESEQUENCE-4"> <para>
<refsect2info> <command>CREATE SEQUENCE</command> is a
<date>1998-09-11</date> <productname>PostgreSQL</productname> language extension. There is
</refsect2info> no <command>CREATE SEQUENCE</command> statement in the SQL
<title> standard.
SQL92 </para>
</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>
</refsect1> </refsect1>
</refentry> </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 PostgreSQL documentation
--> -->
@ -29,7 +29,7 @@ where <replaceable class="PARAMETER">column_constraint</replaceable> is:
[ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ] [ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ]
{ NOT NULL | NULL | UNIQUE | PRIMARY KEY | { NOT NULL | NULL | UNIQUE | PRIMARY KEY |
CHECK (<replaceable class="PARAMETER">expression</replaceable>) | 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> ] } [ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON UPDATE <replaceable class="parameter">action</replaceable> ] }
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ] [ 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> [, ... ] ) | PRIMARY KEY ( <replaceable class="PARAMETER">column_name</replaceable> [, ... ] ) |
CHECK ( <replaceable class="PARAMETER">expression</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> [, ... ] ) ] 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 ] [ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
</synopsis> </synopsis>
@ -58,17 +58,16 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<para> <para>
If a schema name is given (for example, <literal>CREATE TABLE If a schema name is given (for example, <literal>CREATE TABLE
myschema.mytable ...</>) then the table is created in the myschema.mytable ...</>) then the table is created in the
specified schema. Otherwise it is created in the current schema (the one specified schema. Otherwise it is created in the current schema.
at the front of the search path; see <literal>CURRENT_SCHEMA()</>). Temporary tables exist in a special schema, so a schema name may not be
TEMP tables exist in a special schema, so a schema name may not be given when creating a temporary table.
given when creating a TEMP table.
The table name must be distinct from the name of any other table, The table name must be distinct from the name of any other table,
sequence, index, or view in the same schema. sequence, index, or view in the same schema.
</para> </para>
<para> <para>
<command>CREATE TABLE</command> also automatically creates a data <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 to one row of the table. Therefore, tables cannot have the same
name as any existing data type in the same schema. name as any existing data type in the same schema.
</para> </para>
@ -81,9 +80,8 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<para> <para>
The optional constraint clauses specify constraints (or tests) that The optional constraint clauses specify constraints (or tests) that
new or updated rows must satisfy for an insert or update operation new or updated rows must satisfy for an insert or update operation
to succeed. A constraint is a named rule: an SQL object which to succeed. A constraint is an SQL object that helps define the
helps define valid sets of values by putting limits on the results set of valid values in the table in various ways.
of insert, update, or delete operations performed on a table.
</para> </para>
<para> <para>
@ -158,7 +156,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<para> <para>
The <literal>DEFAULT</> clause assigns a default data value for The <literal>DEFAULT</> clause assigns a default data value for
the column whose column definition it appears within. The value 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 to other columns in the current table are not allowed). The
data type of the default expression must match the data type of the data type of the default expression must match the data type of the
column. column.
@ -167,7 +165,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<para> <para>
The default expression will be used in any insert operation that The default expression will be used in any insert operation that
does not specify a value for the column. If there is no default 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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -212,7 +210,8 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><literal>WITH OIDS</> or <literal>WITHOUT OIDS</></term> <term><literal>WITH OIDS</></term>
<term><literal>WITHOUT OIDS</></term>
<listitem> <listitem>
<para> <para>
This optional clause specifies whether rows of the new table 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> <term><literal>NOT NULL</></term>
<listitem> <listitem>
<para> <para>
The column is not allowed to contain NULL values. The column is not allowed to contain null values.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -259,7 +258,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<term><literal>NULL</></term> <term><literal>NULL</></term>
<listitem> <listitem>
<para> <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>
<para> <para>
@ -276,7 +275,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<listitem> <listitem>
<para> <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 group of one or more distinct columns of a table may contain
only unique values. The behavior of the unique table constraint only unique values. The behavior of the unique table constraint
is the same as that for column constraints, with the additional 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>
<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. considered equal.
</para> </para>
@ -303,11 +302,11 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<listitem> <listitem>
<para> <para>
The primary key constraint specifies that a column or columns of a table 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 Technically, <literal>PRIMARY KEY</literal> is merely a
combination of <literal>UNIQUE</> and <literal>NOT NULL</>, but combination of <literal>UNIQUE</> and <literal>NOT NULL</>, but
identifying a set of columns as primary key also provides 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 implies that other tables
may rely on this set of columns as a unique identifier for rows. may rely on this set of columns as a unique identifier for rows.
</para> </para>
@ -329,21 +328,19 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<term><literal>CHECK (<replaceable class="PARAMETER">expression</replaceable>)</literal></term> <term><literal>CHECK (<replaceable class="PARAMETER">expression</replaceable>)</literal></term>
<listitem> <listitem>
<para> <para>
<literal>CHECK</> clauses specify integrity constraints or tests The <literal>CHECK</> clause specifies an expression producing a
which new or updated rows must satisfy for an insert or update Boolean result which new or updated rows must satisfy for an
operation to succeed. Each constraint must be an expression insert or update operation to succeed. A check constraint
producing a Boolean result. A condition appearing within a specified as a column constraint should reference that column's
column definition should reference that column's value only, value only, while an expression appearing in a table constraint
while a condition appearing as a table constraint may reference may reference multiple columns.
multiple columns.
</para> </para>
<para> <para>
Currently, <literal>CHECK</literal> expressions cannot contain 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. current row.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -360,7 +357,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<listitem> <listitem>
<para> <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 that a group of one or more columns of the new table must only
contain values which match against values in the referenced contain values which match against values in the referenced
column(s) <replaceable class="parameter">refcolumn</replaceable> column(s) <replaceable class="parameter">refcolumn</replaceable>
@ -374,23 +371,23 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
</para> </para>
<para> <para>
A value added to these columns is matched against the values of A value inserted into these columns is matched against the
the referenced table and referenced columns using the given values of the referenced table and referenced columns using the
match type. There are three match types: <literal>MATCH given match type. There are three match types: <literal>MATCH
FULL</>, <literal>MATCH PARTIAL</>, and a default match type if FULL</>, <literal>MATCH PARTIAL</>, and <literal>MATCH
none is specified. <literal>MATCH FULL</> will not allow one SIMPLE</literal>, which is also the default. <literal>MATCH
column of a multicolumn foreign key to be NULL unless all FULL</> will not allow one column of a multicolumn foreign key
foreign key columns are NULL. The default match type allows some to be null unless all foreign key columns are null.
foreign key columns to be NULL while other parts of the foreign <literal>MATCH SIMPLE</literal> allows some foreign key columns
key are not NULL. <literal>MATCH PARTIAL</> is not yet to be null while other parts of the foreign key are not
implemented. null. <literal>MATCH PARTIAL</> is not yet implemented.
</para> </para>
<para> <para>
In addition, when the data in the referenced columns is changed, In addition, when the data in the referenced columns is changed,
certain actions are performed on the data in this table's certain actions are performed on the data in this table's
columns. The <literal>ON DELETE</literal> clause specifies the 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> being deleted. Likewise, the <literal>ON UPDATE</literal>
clause specifies the action to perform when a referenced column clause specifies the action to perform when a referenced column
in the referenced table is being updated to a new value. If the 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> <term><literal>SET NULL</literal></term>
<listitem> <listitem>
<para> <para>
Set the referencing column values to NULL. Set the referencing column values to null.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -449,19 +446,20 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para> </para>
<para> <para>
If primary key column is updated frequently, it may be wise to If primary key column is updated frequently, it may be wise to
add an index to the <literal>REFERENCES</literal> column so that add an index to the foreign key column so that <literal>NO
<literal>NO ACTION</literal> and <literal>CASCADE</literal> ACTION</literal> and <literal>CASCADE</literal> actions
actions associated with the <literal>REFERENCES</literal> associated with the foreign key column can be more efficiently
column can be more efficiently performed. performed.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><literal>DEFERRABLE</literal> or <literal>NOT DEFERRABLE</literal></term> <term><literal>DEFERRABLE</literal></term>
<term><literal>NOT DEFERRABLE</literal></term>
<listitem> <listitem>
<para> <para>
This controls whether the constraint can be deferred. A This controls whether the constraint can be deferred. A
@ -477,7 +475,8 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
</varlistentry> </varlistentry>
<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> <listitem>
<para> <para>
If a constraint is deferrable, this clause specifies the default 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"> <refsect1 id="SQL-CREATETABLE-diagnostics">
<title>Diagnostics</title> <title>Diagnostics</title>
<msgset> <variablelist>
<msgentry> <varlistentry>
<msg> <term><computeroutput>CREATE TABLE</computeroutput></term>
<msgmain> <listitem>
<msgtext>
<simpara><computeroutput>CREATE TABLE</computeroutput></simpara>
</msgtext>
</msgmain>
</msg>
<msgexplan>
<para> <para>
Message returned if table is successfully created. Message returned if the table was successfully created.
</para> </para>
</msgexplan> </listitem>
</msgentry> </varlistentry>
</variablelist>
<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>
</refsect1> </refsect1>
@ -622,17 +592,6 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
</para> </para>
</listitem> </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> <listitem>
<para> <para>
Unique constraints and primary keys are not inherited in the Unique constraints and primary keys are not inherited in the
@ -653,19 +612,19 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<programlisting> <programlisting>
CREATE TABLE films ( CREATE TABLE films (
code CHARACTER(5) CONSTRAINT firstkey PRIMARY KEY, code char(5) CONSTRAINT firstkey PRIMARY KEY,
title CHARACTER VARYING(40) NOT NULL, title varchar(40) NOT NULL,
did DECIMAL(3) NOT NULL, did integer NOT NULL,
date_prod DATE, date_prod date,
kind CHAR(10), kind varchar(10),
len INTERVAL HOUR TO MINUTE len interval hour to minute
); );
</programlisting> </programlisting>
<programlisting> <programlisting>
CREATE TABLE distributors ( CREATE TABLE distributors (
did DECIMAL(3) PRIMARY KEY DEFAULT NEXTVAL('serial'), did integer PRIMARY KEY DEFAULT nextval('serial'),
name VARCHAR(40) NOT NULL CHECK (name &lt;&gt; '') name varchar(40) NOT NULL CHECK (name &lt;&gt; '')
); );
</programlisting> </programlisting>
</para> </para>
@ -675,23 +634,24 @@ CREATE TABLE distributors (
<programlisting> <programlisting>
CREATE TABLE array ( CREATE TABLE array (
vector INT[][] vector int[][]
); );
</programlisting> </programlisting>
</para> </para>
<para> <para>
Define a unique table constraint for the table films. Unique table Define a unique table constraint for the table
constraints can be defined on one or more columns of the table: <literal>films</literal>. Unique table constraints can be defined
on one or more columns of the table.
<programlisting> <programlisting>
CREATE TABLE films ( CREATE TABLE films (
code CHAR(5), code char(5),
title VARCHAR(40), title varchar(40),
did DECIMAL(3), did integer,
date_prod DATE, date_prod date,
kind VARCHAR(10), kind varchar(10),
len INTERVAL HOUR TO MINUTE, len interval hour to minute,
CONSTRAINT production UNIQUE(date_prod) CONSTRAINT production UNIQUE(date_prod)
); );
</programlisting> </programlisting>
@ -702,8 +662,8 @@ CREATE TABLE films (
<programlisting> <programlisting>
CREATE TABLE distributors ( CREATE TABLE distributors (
did DECIMAL(3) CHECK (did > 100), did integer CHECK (did > 100),
name VARCHAR(40) name varchar(40)
); );
</programlisting> </programlisting>
</para> </para>
@ -713,8 +673,8 @@ CREATE TABLE distributors (
<programlisting> <programlisting>
CREATE TABLE distributors ( CREATE TABLE distributors (
did DECIMAL(3), did integer,
name VARCHAR(40) name varchar(40)
CONSTRAINT con1 CHECK (did > 100 AND name &lt;&gt; '') CONSTRAINT con1 CHECK (did > 100 AND name &lt;&gt; '')
); );
</programlisting> </programlisting>
@ -727,12 +687,12 @@ CREATE TABLE distributors (
<programlisting> <programlisting>
CREATE TABLE films ( CREATE TABLE films (
code CHAR(5), code char(5),
title VARCHAR(40), title varchar(40),
did DECIMAL(3), did integer,
date_prod DATE, date_prod date,
kind VARCHAR(10), kind varchar(10),
len INTERVAL HOUR TO MINUTE, len interval hour to minute,
CONSTRAINT code_title PRIMARY KEY(code,title) CONSTRAINT code_title PRIMARY KEY(code,title)
); );
</programlisting> </programlisting>
@ -746,33 +706,33 @@ CREATE TABLE films (
<programlisting> <programlisting>
CREATE TABLE distributors ( CREATE TABLE distributors (
did DECIMAL(3), did integer,
name CHAR VARYING(40), name varchar(40),
PRIMARY KEY(did) PRIMARY KEY(did)
); );
</programlisting> </programlisting>
<programlisting> <programlisting>
CREATE TABLE distributors ( CREATE TABLE distributors (
did DECIMAL(3) PRIMARY KEY, did integer PRIMARY KEY,
name VARCHAR(40) name varchar(40)
); );
</programlisting> </programlisting>
</para> </para>
<para> <para>
This assigns a literal constant default value for the column This assigns a literal constant default value for the column
<literal>name</literal>, and arranges for the default value of <literal>name</literal>, arranges for the default value of column
column <literal>did</literal> to be generated by selecting the next <literal>did</literal> to be generated by selecting the next value
value of a sequence object. The default value of of a sequence object, and makes the default value of
<literal>modtime</literal> will be the time at which the row is <literal>modtime</literal> be the time at which the row is
inserted. inserted.
<programlisting> <programlisting>
CREATE TABLE distributors ( CREATE TABLE distributors (
name VARCHAR(40) DEFAULT 'luso films', name varchar(40) DEFAULT 'Luso Films',
did INTEGER DEFAULT NEXTVAL('distributors_serial'), did integer DEFAULT nextval('distributors_serial'),
modtime TIMESTAMP DEFAULT CURRENT_TIMESTAMP modtime timestamp DEFAULT current_timestamp
); );
</programlisting> </programlisting>
</para> </para>
@ -784,8 +744,8 @@ CREATE TABLE distributors (
<programlisting> <programlisting>
CREATE TABLE distributors ( CREATE TABLE distributors (
did DECIMAL(3) CONSTRAINT no_null NOT NULL, did integer CONSTRAINT no_null NOT NULL,
name VARCHAR(40) NOT NULL name varchar(40) NOT NULL
); );
</programlisting> </programlisting>
</para> </para>
@ -795,8 +755,8 @@ CREATE TABLE distributors (
<programlisting> <programlisting>
CREATE TABLE distributors ( CREATE TABLE distributors (
did DECIMAL(3), did integer,
name VARCHAR(40) UNIQUE name varchar(40) UNIQUE
); );
</programlisting> </programlisting>
@ -804,8 +764,8 @@ CREATE TABLE distributors (
<programlisting> <programlisting>
CREATE TABLE distributors ( CREATE TABLE distributors (
did DECIMAL(3), did integer,
name VARCHAR(40), name varchar(40),
UNIQUE(name) UNIQUE(name)
); );
</programlisting> </programlisting>
@ -818,8 +778,7 @@ CREATE TABLE distributors (
<para> <para>
The <command>CREATE TABLE</command> command conforms to SQL92 The <command>CREATE TABLE</command> command conforms to SQL92
and to a subset of SQL99, with exceptions listed below and in the and to a subset of SQL99, with exceptions listed below.
descriptions above.
</para> </para>
<refsect2> <refsect2>
@ -827,27 +786,25 @@ CREATE TABLE distributors (
<para> <para>
Although the syntax of <literal>CREATE TEMPORARY TABLE</literal> 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 temporary tables are defined just once and automatically exist (starting
with empty contents) in every session that needs them. with empty contents) in every session that needs them.
<productname>PostgreSQL</productname> instead <productname>PostgreSQL</productname> instead
requires each session to issue its own <literal>CREATE TEMPORARY requires each session to issue its own <literal>CREATE TEMPORARY
TABLE</literal> command for each temporary table to be used. This allows TABLE</literal> command for each temporary table to be used. This allows
different sessions to use the same temporary table name for different 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. given temporary table name to have the same table structure.
</para> </para>
<note> <para>
<para> The behavior of temporary tables mandated by the standard is
The spec-mandated behavior of temporary tables is widely ignored. widely ignored. <productname>PostgreSQL</productname>'s behavior
<productname>PostgreSQL</productname>'s behavior on this point is similar on this point is similar to that of several other SQL databases.
to that of several other RDBMSs. </para>
</para>
</note>
<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 is not in <productname>PostgreSQL</productname>, since that distinction
depends on the concept of modules, which depends on the concept of modules, which
<productname>PostgreSQL</productname> does not have. <productname>PostgreSQL</productname> does not have.
@ -855,12 +812,24 @@ CREATE TABLE distributors (
<para> <para>
The <literal>ON COMMIT</literal> clause for temporary tables The <literal>ON COMMIT</literal> clause for temporary tables
also resembles SQL92, but has some differences. also resembles the SQL standard, but has some differences.
If the <literal>ON COMMIT</> clause is omitted, SQL92 specifies that the If the <literal>ON COMMIT</> clause is omitted, SQL specifies that the
default behavior is <literal>ON COMMIT DELETE ROWS</>. However, the default behavior is <literal>ON COMMIT DELETE ROWS</>. However, the
default behavior in <productname>PostgreSQL</productname> is default behavior in <productname>PostgreSQL</productname> is
<literal>ON COMMIT PRESERVE ROWS</literal>. The <literal>ON COMMIT <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> </para>
</refsect2> </refsect2>
@ -870,49 +839,13 @@ CREATE TABLE distributors (
<para> <para>
The <literal>NULL</> <quote>constraint</quote> (actually a The <literal>NULL</> <quote>constraint</quote> (actually a
non-constraint) is a <productname>PostgreSQL</productname> non-constraint) is a <productname>PostgreSQL</productname>
extension to SQL92 that is included for compatibility with some extension to the SQL standard that is included for compatibility with some
other RDBMSs (and for symmetry with the <literal>NOT other database systems (and for symmetry with the <literal>NOT
NULL</literal> constraint). Since it is the default for any NULL</literal> constraint). Since it is the default for any
column, its presence is simply noise. column, its presence is simply noise.
</para> </para>
</refsect2> </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> <refsect2>
<title>Inheritance</title> <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 PostgreSQL documentation
--> -->
@ -18,16 +18,12 @@ PostgreSQL documentation
<synopsis> <synopsis>
CREATE [ [ LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replaceable> [ (<replaceable>column_name</replaceable> [, ...] ) ] CREATE [ [ LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replaceable> [ (<replaceable>column_name</replaceable> [, ...] ) ]
AS <replaceable>query</replaceable> AS <replaceable>query</replaceable>
</synopsis> </synopsis>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<refsect1info> <title>Description</title>
<date>2001-03-20</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>CREATE TABLE AS</command> creates a table and fills it <command>CREATE TABLE AS</command> creates a table and fills it
with data computed by a <command>SELECT</command> command. The 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> <term><replaceable>column_name</replaceable></term>
<listitem> <listitem>
<para> <para>
The name of a column in the new table. Multiple column names can The name of a column in the new table. If column names are not
be specified using a comma-delimited list of column names. If provided, they are taken from the output column names of the
column names are not provided, they are taken from the output query.
column names of the query.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -124,21 +119,12 @@ CREATE [ [ LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replace
<para> <para>
This command is modeled after an <productname>Oracle</productname> This command is modeled after an <productname>Oracle</productname>
feature. There is no command with equivalent functionality in 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 TABLE</literal> and <literal>INSERT ... SELECT</literal> can
accomplish the same thing with little more effort. accomplish the same thing with little more effort.
</para> </para>
</refsect1> </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> <refsect1>
<title>See Also</title> <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 PostgreSQL documentation
--> -->
@ -8,186 +8,57 @@ PostgreSQL documentation
<refentrytitle id="SQL-CREATETRIGGER-TITLE">CREATE TRIGGER</refentrytitle> <refentrytitle id="SQL-CREATETRIGGER-TITLE">CREATE TRIGGER</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>CREATE TRIGGER</refname>
CREATE TRIGGER <refpurpose>define a new trigger</refpurpose>
</refname>
<refpurpose>
define a new trigger
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>2000-03-25</date>
</refsynopsisdivinfo>
<synopsis>
CREATE TRIGGER <replaceable class="PARAMETER">name</replaceable> { BEFORE | AFTER } { <replaceable class="PARAMETER">event</replaceable> [ OR ... ] } 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 } ] ON <replaceable class="PARAMETER">table</replaceable> [ FOR [ EACH ] { ROW | STATEMENT } ]
EXECUTE PROCEDURE <replaceable class="PARAMETER">func</replaceable> ( <replaceable class="PARAMETER">arguments</replaceable> ) EXECUTE PROCEDURE <replaceable class="PARAMETER">func</replaceable> ( <replaceable class="PARAMETER">arguments</replaceable> )
</synopsis> </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>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-CREATETRIGGER-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-09-21</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>CREATE TRIGGER</command> will enter a new trigger into the current <command>CREATE TRIGGER</command> creates a new trigger. The
database. The trigger will be associated with the relation trigger will be associated with the specified table and will
<replaceable class="parameter">table</replaceable> and will execute execute the specified function <replaceable
the specified function <replaceable class="parameter">func</replaceable>. class="parameter">func</replaceable> when certain events occur.
</para> </para>
<para> <para>
The trigger can be specified to fire either before BEFORE the The trigger can be specified to fire either before before the
operation is attempted on a tuple (before constraints are checked and operation is attempted on a row (before constraints are checked and
the <command>INSERT</command>, <command>UPDATE</command> or the <command>INSERT</command>, <command>UPDATE</command>, or
<command>DELETE</command> is attempted) or AFTER the operation has <command>DELETE</command> is attempted) or after the operation has
been attempted (e.g., after constraints are checked and the completed (after constraints are checked and the
<command>INSERT</command>, <command>UPDATE</command> or <command>INSERT</command>, <command>UPDATE</command>, or
<command>DELETE</command> has completed). If the trigger fires before <command>DELETE</command> has completed). If the trigger fires
the event, the trigger may skip the operation for the current tuple, before the event, the trigger may skip the operation for the
or change the tuple being inserted (for <command>INSERT</command> and current row, or change the row being inserted (for
<command>UPDATE</command> operations only). If the trigger fires <command>INSERT</command> and <command>UPDATE</command> operations
after the event, all changes, including the last insertion, update, only). If the trigger fires after the event, all changes, including
or deletion, are <quote>visible</quote> to the trigger. the last insertion, update, or deletion, are <quote>visible</quote>
to the trigger.
</para> </para>
<para> <para>
A trigger that executes <literal>FOR EACH ROW</literal> of the A trigger that is marked <literal>FOR EACH ROW</literal> is called
specified operation is called once for every row that the operation once for every row that the operation modifies. For example, a
modifies. For example, a <command>DELETE</command> that affects 10 <command>DELETE</command> that affects 10 rows will cause any
rows will cause any <literal>ON DELETE</literal> triggers on the <literal>ON DELETE</literal> triggers on the target relation to be
target relation to be called 10 separate times, once for each called 10 separate times, once for each deleted row. In contrast, a
deleted tuple. In contrast, a trigger that executes <literal>FOR trigger that is marked <literal>FOR EACH STATEMENT</literal> only
EACH STATEMENT</literal> of the specified operation only executes executes once for any given operation, regardless of how many rows
once for any given operation, regardless of how many rows it it modifies (in particular, an operation that modifies zero rows
modifies (in particular, an operation that modifies zero rows will will still result in the execution of any applicable <literal>FOR
still result in the execution of any applicable <literal>FOR EACH EACH STATEMENT</literal> triggers).
STATEMENT</literal> triggers).
</para> </para>
<para> <para>
@ -202,9 +73,114 @@ CREATE TRIGGER
</para> </para>
<para> <para>
Refer to <xref linkend="server-programming"> for more information. Refer to <xref linkend="triggers"> for more information about triggers.
</para> </para>
</refsect1> </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"> <refsect1 id="SQL-CREATETRIGGER-notes">
<title>Notes</title> <title>Notes</title>
@ -219,13 +195,13 @@ CREATE TRIGGER
necessary to declare trigger functions as returning the placeholder necessary to declare trigger functions as returning the placeholder
type <type>opaque</>, rather than <type>trigger</>. To support loading type <type>opaque</>, rather than <type>trigger</>. To support loading
of old dump files, <command>CREATE TRIGGER</> will accept a function 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</>. change the function's declared return type to <type>trigger</>.
</para> </para>
<para> <para>
Refer to the <xref linkend="sql-droptrigger" endterm="sql-droptrigger-title"> command for Use <xref linkend="sql-droptrigger"
information on how to remove triggers. endterm="sql-droptrigger-title"> to remove a trigger.
</para> </para>
</refsect1> </refsect1>
@ -233,111 +209,64 @@ CREATE TRIGGER
<title>Examples</title> <title>Examples</title>
<para> <para>
Check if the specified distributor code exists in the distributors <xref linkend="trigger-example"> contains a complete example.
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>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="SQL-CREATETRIGGER-compatibility"> <refsect1 id="SQL-CREATETRIGGER-compatibility">
<title>Compatibility</title> <title>Compatibility</title>
<variablelist> <para>
<varlistentry> The <command>CREATE TRIGGER</command> statement in
<term>SQL92</term> <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> <listitem>
<para> <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> </para>
</listitem> </listitem>
</varlistentry>
<varlistentry>
<term>SQL99</term>
<listitem> <listitem>
<para> <para>
The <command>CREATE TRIGGER</command> statement in SQL99 allows you to define aliases for the <quote>old</quote>
<productname>PostgreSQL</productname> implements a subset of the and <quote>new</quote> rows or tables for use in the definition
SQL99 standard. The following functionality is missing: of the triggered action (e.g., <literal>CREATE TRIGGER ... ON
<itemizedlist> tablename REFERENCING OLD ROW AS somename NEW ROW AS othername
<listitem> ...</literal>). Since <productname>PostgreSQL</productname>
<para> allows trigger procedures to be written in any number of
SQL99 allows triggers to fire on updates to specific columns user-defined languages, access to the data is handled in a
(e.g., <literal>AFTER UPDATE OF col1, col2</literal>). language-specific way.
</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.
</para> </para>
</listitem> </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>
<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 PostgreSQL documentation
--> -->
@ -8,22 +8,17 @@ PostgreSQL documentation
<refentrytitle id="sql-createtype-title">CREATE TYPE</refentrytitle> <refentrytitle id="sql-createtype-title">CREATE TYPE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>CREATE TYPE</refname>
CREATE TYPE <refpurpose>define a new data type</refpurpose>
</refname>
<refpurpose>
define a new data type
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-07-20</date> CREATE TYPE <replaceable class="parameter">typename</replaceable> (
</refsynopsisdivinfo> INPUT = <replaceable class="parameter">input_function</replaceable>, OUTPUT = <replaceable class="parameter">output_function</replaceable>
<synopsis> , INTERNALLENGTH = { <replaceable class="parameter">internallength</replaceable> | VARIABLE }
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> ] [ , DEFAULT = <replaceable class="parameter">default</replaceable> ]
[ , ELEMENT = <replaceable class="parameter">element</replaceable> ] [ , DELIMITER = <replaceable class="parameter">delimiter</replaceable> ] [ , ELEMENT = <replaceable class="parameter">element</replaceable> ] [ , DELIMITER = <replaceable class="parameter">delimiter</replaceable> ]
[ , PASSEDBYVALUE ] [ , PASSEDBYVALUE ]
@ -32,184 +27,26 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <rep
) )
CREATE TYPE <replaceable class="parameter">typename</replaceable> AS CREATE TYPE <replaceable class="parameter">typename</replaceable> AS
( <replaceable class="PARAMETER">column_name</replaceable> <replaceable class="PARAMETER">data_type</replaceable> [, ... ] ) ( <replaceable class="PARAMETER">attribute_name</replaceable> <replaceable class="PARAMETER">data_type</replaceable> [, ... ] )
</synopsis> </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>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-CREATETYPE-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-09-21</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>CREATE TYPE</command> allows the user to register a new data <command>CREATE TYPE</command> registers a new data type for use in
type with <productname>PostgreSQL</> for use in the current data base. the current data base. The user who defines a type becomes its
The user who defines a type becomes its owner. owner.
</para> </para>
<para> <para>
If a schema name is given then the type is created in the If a schema name is given then the type is created in the specified
specified schema. Otherwise it is created in the current schema (the one schema. Otherwise it is created in the current schema. The type
at the front of the search path; see <literal>CURRENT_SCHEMA()</>). name must be distinct from the name of any existing type or domain
The type name must be distinct from the name of any existing type or in the same schema. (Because tables have associated data types,
domain in the same schema. (Because tables have associated data types, the type name must also be distinct from the name of any existing
type names also must not conflict with table names in the same schema.) table in the same schema.)
</para> </para>
<refsect2> <refsect2>
@ -220,74 +57,59 @@ CREATE TYPE
(scalar type). It requires the (scalar type). It requires the
registration of two functions (using <command>CREATE registration of two functions (using <command>CREATE
FUNCTION</command>) before defining the 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 <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 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> <replaceable class="parameter">output_function</replaceable>
performs the reverse transformation. The input function may be performs the reverse transformation. The input function may be
declared as taking one argument of type <type>cstring</type>, declared as taking one argument of type <type>cstring</type>,
or as taking three arguments of types or as taking three arguments of types
<type>cstring</type>, <type>OID</type>, <type>int4</type>. <type>cstring</type>, <type>oid</type>, <type>integer</type>.
(The first argument is the input text as a C string, the second 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, 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. It should return a value of the data type itself.
The output function may be The output function may be
declared as taking one argument of the new data type, or as taking declared as taking one argument of the new data type, or as taking
two arguments of which the second is type <type>OID</type>. two arguments of which the second is type <type>oid</type>.
(The second argument is again the array element type for array types.) The second argument is again the array element type for array types.
The output function should return type <type>cstring</type>. The output function should return type <type>cstring</type>.
</para> </para>
<para> <para>
You should at this point be wondering how the input and output functions 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 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 input function must be created first, then the output function, then the
data type. data type.
<productname>PostgreSQL</productname> will first see the name of the new <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 data type as the return type of the input function. It will create a
<quote>shell</> type, which is simply a placeholder entry in <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 type. Similarly the output function will be linked to the (now already
existing) shell type. Finally, <command>CREATE TYPE</> replaces the existing) shell type. Finally, <command>CREATE TYPE</> replaces the
shell entry with a complete type definition, and the new type can be used. shell entry with a complete type definition, and the new type can be used.
</para> </para>
<note>
<para> <para>
In <productname>PostgreSQL</productname> versions before 7.3, it was Base data types can be fixed-length, in which case
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
<replaceable class="parameter">internallength</replaceable> is a <replaceable class="parameter">internallength</replaceable> is a
positive integer, or variable length, indicated by setting positive integer, or variable length, indicated by setting
<replaceable class="parameter">internallength</replaceable> <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 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. length of this value of the type.
</para> </para>
<para> <para>
To indicate that a type is an array, To indicate that a type is an array, specify the type of the array
specify the type of the array elements using the <literal>ELEMENT</> key word. For example, to
elements using the <option>ELEMENT</> keyword. For example, to define define an array of 4-byte integers (<type>int4</type>), specify
an array of 4-byte integers ("int4"), specify <literal>ELEMENT = int4</literal> More details about array types
<programlisting>ELEMENT = int4</programlisting> appear below.
More details about array types appear below.
</para> </para>
<para> <para>
@ -295,29 +117,28 @@ CREATE TYPE
representation of arrays of this type, <replaceable representation of arrays of this type, <replaceable
class="parameter">delimiter</replaceable> can be class="parameter">delimiter</replaceable> can be
set to a specific character. The default delimiter is the comma 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. with the array element type, not the array type itself.
</para> </para>
<para> <para>
A default value may be specified, in case a user wants columns of the A default value may be specified, in case a user wants columns of the
data type to default to something other than NULL. data type to default to something other than the null value.
Specify the default with the <option>DEFAULT</option> keyword. Specify the default with the <literal>DEFAULT</literal> key word.
(Such a default may be overridden by an explicit <option>DEFAULT</option> (Such a default may be overridden by an explicit <literal>DEFAULT</literal>
clause attached to a particular column.) clause attached to a particular column.)
</para> </para>
<para> <para>
The optional flag, <option>PASSEDBYVALUE</option>, indicates that The optional flag <literal>PASSEDBYVALUE</literal> indicates that
values of this data type are passed values of this data type are passed by value rather than by
by value rather than by reference. Note that you reference. You may not pass by value types whose internal
may not pass by value types whose internal representation is representation is larger than the size of the <type>Datum</> type
longer than the width of the <type>Datum</> type (four bytes on (4 bytes on most machines, 8 bytes on a few).
most machines, eight bytes on a few).
</para> </para>
<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 specifies the storage alignment required for the data type. The
allowed values equate to alignment on 1, 2, 4, or 8 byte boundaries. 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 Note that variable-length types must have an alignment of at least
@ -325,21 +146,22 @@ CREATE TYPE
</para> </para>
<para> <para>
The <replaceable class="parameter">storage</replaceable> keyword The <replaceable class="parameter">storage</replaceable> parameter
allows selection of storage strategies for variable-length data types allows selection of storage strategies for variable-length data
(only <literal>plain</literal> is allowed for fixed-length types). types. (Only <literal>plain</literal> is allowed for fixed-length
<literal>plain</literal> disables TOAST for the data type: it will always types.) <literal>plain</literal> specifies that data of the type
be stored in-line and not compressed. will always be stored in-line and not compressed.
<literal>extended</literal> gives full TOAST capability: the system will <literal>extended</literal> specifies that the system will first
first try to compress a long data value, and will move the value out of try to compress a long data value, and will move the value out of
the main table row if it's still too long. the main table row if it's still too long.
<literal>external</literal> allows the value to be moved out of the main <literal>external</literal> allows the value to be moved out of the
table, but the system will not try to compress it. main table, but the system will not try to compress it.
<literal>main</literal> allows compression, but discourages moving the <literal>main</literal> allows compression, but discourages moving
value out of the main table. (Data items with this storage method may the value out of the main table. (Data items with this storage
still be moved out of the main table if there is no other way to make strategy may still be moved out of the main table if there is no
a row fit, but they will be kept in the main table preferentially over other way to make a row fit, but they will be kept in the main
<literal>extended</literal> and <literal>external</literal> items.) table preferentially over <literal>extended</literal> and
<literal>external</literal> items.)
</para> </para>
</refsect2> </refsect2>
@ -349,7 +171,7 @@ CREATE TYPE
<para> <para>
The second form of <command>CREATE TYPE</command> The second form of <command>CREATE TYPE</command>
creates a composite type. 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 This is essentially the same as the row type
of a table, but using <command>CREATE TYPE</command> avoids the need to 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. create an actual table when all that is wanted is to define a type.
@ -373,19 +195,19 @@ CREATE TYPE
</para> </para>
<para> <para>
You might reasonably ask <quote>why is there an <option>ELEMENT</> You might reasonably ask why there is an <option>ELEMENT</>
option, if the system makes the correct array type automatically?</quote> 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 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 making a fixed-length type that happens to be internally an array of a number of
identical things, and you want to allow the N things to be accessed identical things, and you want to allow these things to be accessed
directly by subscripting, in addition to whatever operations you plan directly by subscripting, in addition to whatever operations you plan
to provide for the type as a whole. For example, type <type>name</> to provide for the type as a whole. For example, type <type>name</>
allows its constituent <type>char</>s to be accessed this way. allows its constituent <type>char</> elements to be accessed this way.
A 2-D <type>point</> type could allow its two component floats to be A 2-D <type>point</> type could allow its two component numbers to be
accessed like <literal>point[0]</> and <literal>point[1]</>. accessed like <literal>point[0]</> and <literal>point[1]</>.
Note that Note that
this facility only works for fixed-length types whose internal form 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 variable-length type must have the generalized internal representation
used by <literal>array_in</> and <literal>array_out</>. used by <literal>array_in</> and <literal>array_out</>.
For historical reasons (i.e., this is clearly wrong but it's far too For historical reasons (i.e., this is clearly wrong but it's far too
@ -394,41 +216,196 @@ CREATE TYPE
</para> </para>
</refsect2> </refsect2>
</refsect1> </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"> <refsect1 id="SQL-CREATETYPE-notes">
<title>Notes</title> <title>Notes</title>
<para> <para>
User-defined type names cannot begin with the underscore character User-defined type names cannot begin with the underscore character
(<quote><literal>_</literal></quote>) and can only be 62 (<literal>_</literal>) and can only be 62 characters
characters long (or in general <symbol>NAMEDATALEN</symbol> - 2, rather than long (or in general <symbol>NAMEDATALEN</symbol> - 2, rather than
the <symbol>NAMEDATALEN</symbol> - 1 characters allowed for other names). the <symbol>NAMEDATALEN</symbol> - 1 characters allowed for other
Type names beginning with underscore are names). Type names beginning with underscore are reserved for
reserved for internally-created array type names. internally-created array type names.
</para> </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>
<refsect1> <refsect1>
<title>Examples</title> <title>Examples</title>
<para> <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: type in a table definition:
<programlisting> <programlisting>
CREATE TYPE box (INTERNALLENGTH = 16, CREATE TYPE box (
INPUT = my_procedure_1, OUTPUT = my_procedure_2); INTERNALLENGTH = 16,
CREATE TABLE myboxes (id INT4, description box); INPUT = my_box_in_function,
OUTPUT = my_box_out_function
);
CREATE TABLE myboxes (
id integer,
description box
);
</programlisting> </programlisting>
</para> </para>
<para> <para>
If <type>box</type>'s internal structure were an array of four If the internal structure of <type>box</type> were an array of four
<type>float4</>s, we might instead say <type>float4</> elements, we might instead use
<programlisting> <programlisting>
CREATE TYPE box (INTERNALLENGTH = 16, CREATE TYPE box (
INPUT = my_procedure_1, OUTPUT = my_procedure_2, INTERNALLENGTH = 16,
ELEMENT = float4); INPUT = my_box_in_function,
OUTPUT = my_box_out_function,
ELEMENT = float4
);
</programlisting> </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. by subscripting. Otherwise the type behaves the same as before.
</para> </para>
@ -436,20 +413,30 @@ CREATE TYPE box (INTERNALLENGTH = 16,
This example creates a large object type and uses it in This example creates a large object type and uses it in
a table definition: a table definition:
<programlisting> <programlisting>
CREATE TYPE bigobj (INPUT = lo_filein, OUTPUT = lo_fileout, CREATE TYPE bigobj (
INTERNALLENGTH = VARIABLE); INPUT = lo_filein, OUTPUT = lo_fileout,
CREATE TABLE big_objs (id int4, obj bigobj); INTERNALLENGTH = VARIABLE
);
CREATE TABLE big_objs (
id integer,
obj bigobj
);
</programlisting> </programlisting>
</para> </para>
<para> <para>
This example creates a composite type and uses it in This example creates a composite type and uses it in
a table function definition: a function definition:
<programlisting> <programlisting>
CREATE TYPE compfoo AS (f1 int, f2 text); CREATE TYPE compfoo AS (f1 int, f2 text);
CREATE FUNCTION getfoo() RETURNS SETOF compfoo AS 'SELECT fooid, fooname FROM foo' LANGUAGE SQL; CREATE FUNCTION getfoo() RETURNS SETOF compfoo AS 'SELECT fooid, fooname FROM foo' LANGUAGE SQL;
</programlisting> </programlisting>
</para> </para>
<para>
More examples, including suitable input and output functions, are
in <xref linkend="extend">.
</para>
</refsect1> </refsect1>
<refsect1 id="SQL-CREATETYPE-compatibility"> <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 PostgreSQL documentation
--> -->
@ -33,16 +33,17 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
<title>Description</title> <title>Description</title>
<para> <para>
<command>CREATE USER</command> will add a new user to an instance <command>CREATE USER</command> adds a new user to a
of <productname>PostgreSQL</productname>. Refer to <xref linkend="user-manag"> <productname>PostgreSQL</productname> database cluster. Refer to
for information about managing users and authentication. You must <xref linkend="user-manag"> and <xref
be a database superuser to use this command. linkend="client-authentication"> for information about managing
users and authentication. You must be a database superuser to use
this command.
</para> </para>
</refsect1>
<refsect2> <refsect1>
<title>Parameters</title> <title>Parameters</title>
<para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
@ -60,9 +61,9 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
<para> <para>
The <literal>SYSID</literal> clause can be used to choose the The <literal>SYSID</literal> clause can be used to choose the
<productname>PostgreSQL</productname> user ID of the user that <productname>PostgreSQL</productname> user ID of the user that
is being created. It is not at all necessary that those match is being created. This is not normally not necessary, but may
the Unix user IDs, but some people choose to keep the numbers be useful if you need to recreate the owner of an orphaned
the same. object.
</para> </para>
<para> <para>
If this is not specified, the highest assigned user ID plus one 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> <listitem>
<para> <para>
Sets the user's password. If you do not plan to use password Sets the user's password. If you do not plan to use password
authentication you can omit this option, but the user authentication you can omit this option, but then the user
won't be able to connect to a password-authenticated server. won't be able to connect if you decide to switch to password
The password can be set or changed later, using authentication. The password can be set or changed later,
<xref linkend="SQL-ALTERUSER" endterm="SQL-ALTERUSER-title">. using <xref linkend="SQL-ALTERUSER"
endterm="SQL-ALTERUSER-title">.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -89,23 +91,22 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
<term><literal>UNENCRYPTED</></term> <term><literal>UNENCRYPTED</></term>
<listitem> <listitem>
<para> <para>
These keywords control whether the password is stored These key words control whether the password is stored
encrypted in <literal>pg_shadow</>. (If neither is specified, encrypted in the system catalogs. (If neither is specified,
the default behavior is determined by the the default behavior is determined by the configuration
<varname>PASSWORD_ENCRYPTION</varname> server parameter.) If parameter <varname>password_encryption</varname>.) If the
the presented string is already in MD5-encrypted format, then presented password string is already in MD5-encrypted format,
it is stored as-is, regardless of whether then it is stored encrypted as-is, regardless of whether
<literal>ENCRYPTED</> or <literal>UNENCRYPTED</> is specified. <literal>ENCRYPTED</> or <literal>UNENCRYPTED</> is specified
This allows reloading of encrypted passwords during (since the system cannot decrypt the specified encrypted
dump/restore. password string). This allows reloading of encrypted
passwords during dump/restore.
</para> </para>
<para> <para>
See <xref linkend="client-authentication"> Note that older clients may lack support for the MD5
for details on how to set up authentication mechanisms. Note authentication mechanism that is needed to work with passwords
that older clients may lack support for the MD5 authentication that are stored encrypted.
mechanism that is needed to work with passwords that are
stored encrypted.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -160,26 +161,21 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</refsect2>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Diagnostics</title> <title>Diagnostics</title>
<para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><computeroutput>CREATE USER</computeroutput></term> <term><computeroutput>CREATE USER</computeroutput></term>
<listitem> <listitem>
<para> <para>
Message returned if the command completes successfully. Message returned if the user account was successfully created.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
@ -191,9 +187,12 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
endterm="SQL-DROPUSER-title"> to remove a user. Use <xref endterm="SQL-DROPUSER-title"> to remove a user. Use <xref
linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title"> to add the linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title"> to add the
user to groups or remove the user from groups. user to groups or remove the user from groups.
</para>
<para>
<productname>PostgreSQL</productname> includes a program <xref <productname>PostgreSQL</productname> includes a program <xref
linkend="APP-CREATEUSER" endterm="APP-CREATEUSER-title"> that has 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. command) but can be run from the command shell.
</para> </para>
</refsect1> </refsect1>
@ -216,12 +215,12 @@ CREATE USER davide WITH PASSWORD 'jw8s0F4';
</para> </para>
<para> <para>
Create a user with a password, whose account is valid until the end of 2001. Create a user with a password that is valid until the end of 2004.
Note that after one second has ticked in 2002, the account is not After one second has ticked in 2005, the password is no longer
valid: valid.
<programlisting> <programlisting>
CREATE USER miriam WITH PASSWORD 'jw8s0F4' VALID UNTIL 'Jan 1 2002'; CREATE USER miriam WITH PASSWORD 'jw8s0F4' VALID UNTIL '2005-01-01';
</programlisting> </programlisting>
</para> </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 PostgreSQL documentation
--> -->
@ -8,136 +8,26 @@ PostgreSQL documentation
<refentrytitle id="SQL-CREATEVIEW-TITLE">CREATE VIEW</refentrytitle> <refentrytitle id="SQL-CREATEVIEW-TITLE">CREATE VIEW</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>CREATE VIEW</refname>
CREATE VIEW <refpurpose>define a new view</refpurpose>
</refname>
<refpurpose>
define a new view
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>2000-03-25</date> CREATE [ OR REPLACE ] VIEW <replaceable class="PARAMETER">name</replaceable> [ ( <replaceable
</refsynopsisdivinfo> class="PARAMETER">column_name</replaceable> [, ...] ) ] AS <replaceable class="PARAMETER">query</replaceable>
<synopsis> </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>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-CREATEVIEW-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>2000-03-25</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>CREATE VIEW</command> defines a view of a query. <command>CREATE VIEW</command> defines a view of a query. The view
The view is not physically materialized. Instead, a query is not physically materialized. Instead, the query is run everytime
rewrite rule (an <literal>ON SELECT</> rule) is automatically generated to the view is referenced in a query.
support SELECT operations on views.
</para> </para>
<para> <para>
@ -150,19 +40,87 @@ CREATE VIEW vista AS SELECT text 'Hello World'
<para> <para>
If a schema name is given (for example, <literal>CREATE VIEW If a schema name is given (for example, <literal>CREATE VIEW
myschema.myview ...</>) then the view is created in the myschema.myview ...</>) then the view is created in the
specified schema. Otherwise it is created in the current schema (the one specified schema. Otherwise it is created in the current schema.
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
The view name must be distinct from the name of any other view, table, The view name must be distinct from the name of any other view, table,
sequence, or index in the same schema. sequence, or index in the same schema.
</para> </para>
</refsect1>
<refsect2 id="R2-SQL-CREATEVIEW-3"> <refsect1>
<refsect2info> <title>Parameters</title>
<date>2000-03-25</date>
</refsect2info> <variablelist>
<title> <varlistentry>
Notes <term><replaceable class="parameter">name</replaceable></term>
</title> <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> <para>
Currently, views are read only: the system will not allow an insert, 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> <para>
Use the <command>DROP VIEW</command> statement to drop views. Use the <command>DROP VIEW</command> statement to drop views.
</para> </para>
</refsect2>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-CREATEVIEW-2"> <refsect1>
<title> <title>Examples</title>
Usage
</title>
<para>
Create a view consisting of all Comedy films:
<programlisting> <para>
CREATE VIEW kinds AS Create a view consisting of all comedy films:
<programlisting>
CREATE VIEW comedies AS
SELECT * SELECT *
FROM films FROM films
WHERE kind = 'Comedy'; WHERE kind = 'Comedy';
</programlisting>
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>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-CREATEVIEW-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-CREATEVIEW-5">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>
<title>
SQL92
</title>
<para> <para>
SQL92 specifies some additional capabilities for the The SQL standard specifies some additional capabilities for the
<command>CREATE VIEW</command> statement: <command>CREATE VIEW</command> statement:
</para> <synopsis>
<synopsis> CREATE VIEW <replaceable class="parameter">name</replaceable> [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ]
CREATE VIEW <replaceable class="parameter">view</replaceable> [ <replaceable class="parameter">column</replaceable> [, ...] ] AS query
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> ]
[ WITH [ CASCADE | LOCAL ] CHECK OPTION ] [ WITH [ CASCADE | LOCAL ] CHECK OPTION ]
</synopsis> </synopsis>
</para>
<para> <para>
The optional clauses for the full SQL92 command are: The optional clauses for the full SQL command are:
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>CHECK OPTION</term> <term><literal>CHECK OPTION</literal></term>
<listitem> <listitem>
<para> <para>
This option is to do with updatable views. This option is to do with updatable views. All
All <command>INSERT</> and <command>UPDATE</> commands on the view will be <command>INSERT</> and <command>UPDATE</> commands on the view
checked to ensure data satisfy the view-defining will be checked to ensure data satisfy the view-defining
condition. If they do not, the update will be rejected. condition (that is, the new data would be visible through the
view). If they do not, the update will be rejected.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>LOCAL</term> <term><literal>LOCAL</literal></term>
<listitem> <listitem>
<para> <para>
Check for integrity on this view. Check for integrity on this view.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>CASCADE</term> <term><literal>CASCADE</literal></term>
<listitem> <listitem>
<para> <para>
Check for integrity on this view and on any dependent Check for integrity on this view and on any dependent
view. CASCADE is assumed if neither CASCADE nor LOCAL is specified. view. <literal>CASCADE</> is assumed if neither
<literal>CASCADE</> nor <literal>LOCAL</> is specified.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para> </para>
<para> <para>
<command>CREATE OR REPLACE VIEW</command> is a <command>CREATE OR REPLACE VIEW</command> is a
<productname>PostgreSQL</productname> language extension. <productname>PostgreSQL</productname> language extension.
</para> </para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>