database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-12-21 05:21:08 +03:00
Code Activity

Documentation updates to reflect TOAST and new-style fmgr.

Browse Source
This commit is contained in:
Tom Lane
2000-08-24 23:36:29 +00:00
parent 481487b964
commit 0813fcbc08
7 changed files with 474 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
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.15 2000/07/22 04:30:27 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.16 2000/08/24 23:36:29 tgl Exp $
Postgres documentation
-->
@@ -31,7 +31,7 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab
CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">ftype</replaceable> [, ...] ] )
RETURNS <replaceable class="parameter">rtype</replaceable>
AS <replaceable class="parameter">obj_file</replaceable> , <replaceable class="parameter">link_symbol</replaceable>
LANGUAGE 'C'
LANGUAGE 'langname'
[ WITH ( <replaceable class="parameter">attribute</replaceable> [, ...] ) ]
</synopsis>
@@ -57,11 +57,11 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab
<term><replaceable class="parameter">ftype</replaceable></term>
<listitem>
<para>
The data type of function arguments.
The data type(s) of the function's arguments, if any.
The input types may be base or complex types, or
<firstterm>opaque</firstterm>.
<literal>opaque</literal> indicates that the function
accepts arguments of an invalid type such as <type>char *</type>.
accepts arguments of a non-SQL type such as <type>char *</type>.
</para>
</listitem>
</varlistentry>
@@ -84,14 +84,7 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab
<listitem>
<para>
An optional piece of information about the function, used for
optimization. The only attribute currently supported is
<literal>iscachable</literal>.
<literal>iscachable</literal> indicates that the function always
returns the same result when given the same input values (i.e.,
it does not do database lookups or otherwise use information not
directly present in its parameter list). The optimizer uses
<literal>iscachable</literal> to know whether it is safe to
pre-evaluate a call of the function.
optimization. See below for details.
</para>
</listitem>
</varlistentry>
@@ -115,8 +108,8 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab
function. The string <replaceable
class="parameter">obj_file</replaceable> is the name of the file
containing the dynamically loadable object, and <replaceable
class="parameter">link_symbol</replaceable>, is the object's link
symbol which is the same as the name of the function in the C
class="parameter">link_symbol</replaceable> is the object's link
symbol, that is the name of the function in the C
language source code.
</para>
</listitem>
@@ -125,8 +118,9 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab
<term><replaceable class="parameter">langname</replaceable></term>
<listitem>
<para>
may be '<literal>C</literal>', '<literal>sql</literal>',
'<literal>internal</literal>'
may be '<literal>sql</literal>',
'<literal>C</literal>', '<literal>newC</literal>',
'<literal>internal</literal>', '<literal>newinternal</literal>',
or '<replaceable class="parameter">plname</replaceable>',
where '<replaceable class="parameter">plname</replaceable>'
is the name of a created procedural language. See
@@ -175,11 +169,57 @@ CREATE
<command>CREATE FUNCTION</command> allows a
<productname>Postgres</productname> user
to register a function
with a database. Subsequently, this user is considered the
with the database. Subsequently, this user is considered the
owner of the function.
</para>
<refsect2 id="R2-SQL-CREATEFUNCTION-3">
<refsect2info>
<date>2000-08-24</date>
</refsect2info>
<title>
Function Attributes
</title>
<para>
The following items may appear in the WITH clause:
<variablelist>
<varlistentry>
<literal>iscachable</literal>
<listitem>
<para>
<literal>iscachable</literal> indicates that the function always
returns the same result when given the same argument values (i.e.,
it does not do database lookups or otherwise use information not
directly present in its parameter list). The optimizer uses
<literal>iscachable</literal> to know whether it is safe to
pre-evaluate a call of the function.
</para>
</listitem>
</varlistentry>
<varlistentry>
<literal>isstrict</literal>
<listitem>
<para>
<literal>isstrict</literal> indicates that the function always
returns NULL whenever any of its arguments are NULL. If this
attribute is specified, the function is not executed when there
are NULL arguments; instead a NULL result is assumed automatically.
When <literal>isstrict</literal> is not specified, the function will
be called for NULL inputs. It is then the function author's
responsibility to check for NULLs if necessary and respond
appropriately.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-CREATEFUNCTION-4">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>
@@ -200,26 +240,25 @@ CREATE
to remove user-defined functions.
</para>
<para>
<productname>Postgres</productname> allows function "overloading";
that is, the same name can be used for several different functions
so long as they have distinct argument types. This facility must
be used with caution for <literal>internal</literal> and
C-language functions, however.
</para>
<para>
The full <acronym>SQL92</acronym> type syntax is allowed for
input arguments and return value. However, some details of the
type specification (e.g. the precision field for
<type>numeric</type> types) are the responsibility of the
underlying function implementation and are silently swallowed
(e.g. not recognized or
(i.e., not recognized or
enforced) by the <command>CREATE FUNCTION</command> command.
</para>
<para>
Two <literal>internal</literal>
<productname>Postgres</productname> allows function "overloading";
that is, the same name can be used for several different functions
so long as they have distinct argument types. This facility must
be used with caution for internal and C-language functions, however.
</para>
<para>
Two <literal>internal</literal> or <literal>newinternal</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
@@ -229,18 +268,14 @@ CREATE
</para>
<para>
When overloading SQL functions with C-language functions, give
each C-language instance of the function a distinct name, and use
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 ensure that
overloaded SQL functions names are resolved to the correct
dynamically linked objects.
<command>CREATE FUNCTION</command> syntax to select the appropriate
C-language implementation of each overloaded SQL function.
</para>
<para>
A C function cannot return a set of values.
</para>
</refsect2>
</refsect1>
@@ -291,7 +326,7 @@ CREATE TABLE product (
function is implemented by a dynamically loaded object that was
compiled from C source. For <productname>Postgres</productname> to
find a type conversion function automatically, the sql function has
to have the same name as the return type, and overloading is
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:
</para>
@@ -324,7 +359,7 @@ Point * complex_to_point (Complex *z)
Compatibility
</title>
<refsect2 id="R2-SQL-CREATEFUNCTION-4">
<refsect2 id="R2-SQL-CREATEFUNCTION-5">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>
@@ -338,7 +373,7 @@ Point * complex_to_point (Complex *z)
</para>
</refsect2>
<refsect2 id="R2-SQL-CREATEFUNCTION-5">
<refsect2 id="R2-SQL-CREATEFUNCTION-6">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>

29
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.10 2000/05/29 01:59:06 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_language.sgml,v 1.11 2000/08/24 23:36:29 tgl Exp $
Postgres documentation
-->
@@ -48,8 +48,7 @@ CREATE [ TRUSTED ] PROCEDURAL LANGUAGE '<replaceable class="parameter">langname<
this keyword is omitted when registering the language,
only users with the <productname>Postgres</productname>
superuser privilege can use
this language to create new functions
(like the 'C' language).
this language to create new functions.
</para>
</listitem>
</varlistentry>
@@ -222,6 +221,11 @@ ERROR: PL handler function <replaceable class="parameter">funcname</replaceable
must be careful that <literal>flinfo-&gt;fn_extra</literal> is made to
point at memory that will live at least until the end of the current
query, since an FmgrInfo data structure could be kept that long.
One way to do this is to allocate the extra data in the memory context
specified by <literal>flinfo-&gt;fn_mcxt</literal>; such data will
normally have the same lifespan as the FmgrInfo itself. But the handler
could also choose to use a longer-lived context so that it can cache
function definition information across queries.
</para>
<para>
@@ -262,20 +266,21 @@ ERROR: PL handler function <replaceable class="parameter">funcname</replaceable
lanplcallfoid | oid |
lancompiler | text |
lanname | lanispl | lanpltrusted | lanplcallfoid | lancompiler
----------+---------+--------------+---------------+-------------
internal | f | f | 0 | n/a
C | f | f | 0 | /bin/cc
sql | f | f | 0 | postgres
lanname | lanispl | lanpltrusted | lanplcallfoid | lancompiler
-------------+---------+--------------+---------------+-------------
internal | f | f | 0 | n/a
newinternal | f | f | 0 | n/a
C | f | f | 0 | /bin/cc
newC | f | f | 0 | /bin/cc
sql | f | f | 0 | postgres
</computeroutput>
</programlisting>
</para>
<para>
Since the call handler for a procedural language must be
registered with <productname>Postgres</productname> in the 'C' language,
it inherits
all the capabilities and restrictions of 'C' functions.
The call handler for a procedural language must normally be written
in C and registered as 'newinternal' or 'newC' language, depending
on whether it is linked into the backend or dynamically loaded.
</para>
<para>

10
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.33 2000/07/22 04:30:27 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table.sgml,v 1.34 2000/08/24 23:36:29 tgl Exp $
Postgres documentation
-->
@@ -248,11 +248,9 @@ ERROR: DEFAULT: type mismatched
<para>
The new table is created as a heap with no initial data.
A table can have no more than 1600 columns (realistically,
this is limited by the fact that tuple sizes must
be less than 8192 bytes), but this limit may be configured
lower at some sites. A table cannot have the same name as
a system catalog table.
A table can have no more than 1600 columns (in practice, the
effective limit is lower because of tuple-length constraints).
A table cannot have the same name as a system catalog table.
</para>
</refsect1>

74
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.12 2000/03/27 17:14:42 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_type.sgml,v 1.13 2000/08/24 23:36:29 tgl Exp $
Postgres documentation
-->
@@ -24,11 +24,16 @@ Postgres documentation
</refsynopsisdivinfo>
<synopsis>
CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <replaceable class="parameter">input_function</replaceable>, OUTPUT = <replaceable class="parameter">output_function</replaceable>
, INTERNALLENGTH = { <replaceable class="parameter">internallength</replaceable> | VARIABLE } [ , EXTERNALLENGTH = { <replaceable class="parameter">externallength</replaceable> | VARIABLE } ]
, INTERNALLENGTH = { <replaceable
class="parameter">internallength</replaceable> | VARIABLE }
[ , EXTERNALLENGTH = { <replaceable class="parameter">externallength</replaceable> | VARIABLE } ]
[ , DEFAULT = "<replaceable class="parameter">default</replaceable>" ]
[ , ELEMENT = <replaceable class="parameter">element</replaceable> ] [ , DELIMITER = <replaceable class="parameter">delimiter</replaceable> ]
[ , SEND = <replaceable class="parameter">send_function</replaceable> ] [ , RECEIVE = <replaceable class="parameter">receive_function</replaceable> ]
[ , PASSEDBYVALUE ] )
[ , PASSEDBYVALUE ]
[ , ALIGNMENT = <replaceable class="parameter">alignment</replaceable> ]
[ , STORAGE = <replaceable class="parameter">storage</replaceable> ]
)
</synopsis>
<refsect2 id="R2-SQL-CREATETYPE-1">
@@ -64,7 +69,7 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <rep
<term><replaceable class="parameter">externallength</replaceable></term>
<listitem>
<para>
A literal value, which specifies the external length of
A literal value, which specifies the external (displayed) length of
the new type.
</para>
</listitem>
@@ -86,7 +91,8 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <rep
<term><replaceable class="parameter">output_function</replaceable></term>
<listitem>
<para>
The name of a function, created by CREATE FUNCTION, which
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>
@@ -107,7 +113,7 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <rep
<term><replaceable class="parameter">delimiter</replaceable></term>
<listitem>
<para>
The delimiter character for the array.
The delimiter character for the array elements.
</para>
</listitem>
</varlistentry>
@@ -116,8 +122,8 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <rep
<term><replaceable class="parameter">default</replaceable></term>
<listitem>
<para>
The default text to be displayed to indicate "data
not present"
The default value for the datatype. Usually this is omitted,
so that the default is NULL.
</para>
</listitem>
</varlistentry>
@@ -141,6 +147,29 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <rep
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">alignment</replaceable></term>
<listitem>
<para>
Storage alignment requirement of the datatype. If specified, must
be '<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 datatype. 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>
</variablelist>
</para>
</refsect2>
@@ -267,6 +296,24 @@ CREATE
more than four bytes.
</para>
<para>
The <replaceable class="parameter">storage</replaceable> keyword
allows selection of TOAST storage method for variable-length datatypes
(only <literal>plain</literal> is allowed for fixed-length types).
<literal>plain</literal> disables TOAST for the datatype: it will always
be stored in-line and not compressed.
<literal>extended</literal> is full TOAST capability: the system will
first try to compress a long data value, and will move the value out of
the main table row if it's still too long.
<literal>external</literal> allows the value to be moved out of the main
table, but the system will not try to compress it.
<literal>main</literal> allows compression, but discourages moving the
value out of the main table. (Data items with this storage method may
still be moved out of the main table if there is no other way to make
a row fit, but they will be kept in the main table preferentially over
<literal>extended</literal> and <literal>external</literal> items.)
</para>
<para>
For new base types, a user can define operators, functions
and aggregates using the appropriate facilities described
@@ -283,17 +330,6 @@ CREATE
</para>
</refsect2>
<refsect2>
<title>Large Object Types</title>
<para>
A "regular" Postgres type can only be 8192 bytes in
length. If you need a larger type you must create a Large
Object type. The interface for these types is discussed
at length in the
<citetitle>PostgreSQL Programmer's Guide</citetitle>.
The length of all large object types is always VARIABLE.
</para>
</refsect2>
</refsect1>
<refsect1>