head	1.44;
access;
symbols
	REL9_0_0:1.44
	REL9_1_ALPHA1:1.44
	REL9_0_RC1:1.44
	REL9_0_BETA4:1.44
	REL9_0_STABLE:1.44.0.2
	REL9_0_BETA3:1.44
	REL9_0_BETA2:1.44
	REL7_4_29:1.25.2.1
	REL8_0_25:1.29
	REL8_1_21:1.30
	REL8_2_17:1.32
	REL8_3_11:1.36
	REL8_4_4:1.37
	REL9_0_BETA1:1.38
	REL9_0_ALPHA5_BRANCH:1.37.0.12
	REL9_0_ALPHA5:1.37
	REL7_4_28:1.25.2.1
	REL8_0_24:1.29
	REL8_1_20:1.30
	REL8_2_16:1.32
	REL8_3_10:1.36
	REL8_4_3:1.37
	REL9_0_ALPHA4:1.37
	REL9_0_ALPHA4_BRANCH:1.37.0.10
	REL8_5_ALPHA3:1.37
	REL8_5_ALPHA3_BRANCH:1.37.0.8
	REL7_4_27:1.25.2.1
	REL8_0_23:1.29
	REL8_1_19:1.30
	REL8_2_15:1.32
	REL8_3_9:1.36
	REL8_4_2:1.37
	REL8_5_ALPHA2:1.37
	REL8_5_ALPHA2_BRANCH:1.37.0.6
	REL7_4_26:1.25.2.1
	REL8_0_22:1.29
	REL8_1_18:1.30
	REL8_2_14:1.32
	REL8_3_8:1.36
	REL8_4_1:1.37
	REL8_5_ALPHA1:1.37
	REL8_5_ALPHA1_BRANCH:1.37.0.4
	REL8_4_STABLE:1.37.0.2
	REL8_4_0:1.37
	REL8_4_RC2:1.37
	REL8_4_RC1:1.37
	REL8_4_BETA2:1.37
	REL8_4_BETA1:1.37
	REL7_4_25:1.25.2.1
	REL8_0_21:1.29
	REL8_1_17:1.30
	REL8_2_13:1.32
	REL8_3_7:1.36
	REL7_4_24:1.25.2.1
	REL8_0_20:1.29
	REL8_1_16:1.30
	REL8_2_12:1.32
	REL8_3_6:1.36
	REL7_4_23:1.25.2.1
	REL8_0_19:1.29
	REL8_1_15:1.30
	REL8_2_11:1.32
	REL8_3_5:1.36
	REL7_4_22:1.25.2.1
	REL8_0_18:1.29
	REL8_1_14:1.30
	REL8_2_10:1.32
	REL8_3_4:1.36
	REL7_4_21:1.25.2.1
	REL8_0_17:1.29
	REL8_1_13:1.30
	REL8_2_9:1.32
	REL8_3_3:1.36
	REL7_4_20:1.25.2.1
	REL8_0_16:1.29
	REL8_1_12:1.30
	REL8_2_8:1.32
	REL8_3_2:1.36
	REL8_2_7:1.32
	REL8_3_1:1.36
	REL8_3_STABLE:1.36.0.2
	REL8_3_0:1.36
	REL8_3_RC2:1.36
	REL7_3_21:1.18
	REL7_4_19:1.25.2.1
	REL8_0_15:1.29
	REL8_1_11:1.30
	REL8_2_6:1.32
	REL8_3_RC1:1.36
	REL8_3_BETA4:1.36
	REL8_3_BETA3:1.36
	REL8_3_BETA2:1.36
	REL8_3_BETA1:1.36
	REL7_3_20:1.18
	REL7_4_18:1.25.2.1
	REL8_0_14:1.29
	REL8_1_10:1.30
	REL8_2_5:1.32
	REL7_3_19:1.18
	REL7_4_17:1.25.2.1
	REL8_0_13:1.29
	REL8_1_9:1.30
	REL8_2_4:1.32
	REL8_0_12:1.29
	REL8_1_8:1.30
	REL8_2_3:1.32
	REL7_3_18:1.18
	REL7_4_16:1.25.2.1
	REL8_0_11:1.29
	REL8_1_7:1.30
	REL8_2_2:1.32
	REL8_0_10:1.29
	REL8_1_6:1.30
	REL8_2_1:1.32
	REL7_4_15:1.25.2.1
	REL7_3_17:1.18
	REL8_2_STABLE:1.32.0.2
	REL8_2_0:1.32
	REL8_2_RC1:1.32
	REL8_2_BETA3:1.32
	REL8_2_BETA2:1.32
	REL8_1_5:1.30
	REL8_0_9:1.29
	REL7_4_14:1.25.2.1
	REL7_3_16:1.18
	REL8_2_BETA1:1.32
	REL7_3_15:1.18
	REL7_4_13:1.25.2.1
	REL8_0_8:1.29
	REL8_1_4:1.30
	REL7_3_14:1.18
	REL7_4_12:1.25.2.1
	REL8_0_7:1.29
	REL8_1_3:1.30
	REL7_3_13:1.18
	REL7_4_11:1.25.2.1
	REL8_0_6:1.29
	REL8_1_2:1.30
	REL7_3_12:1.18
	REL7_4_10:1.25.2.1
	REL8_0_5:1.29
	REL8_1_1:1.30
	REL8_1_STABLE:1.30.0.2
	REL8_1_0:1.30
	REL8_1_0RC1:1.30
	REL8_1_0BETA4:1.30
	REL8_1_0BETA3:1.29
	REL7_3_11:1.18
	REL7_4_9:1.25.2.1
	REL8_0_4:1.29
	REL8_1_0BETA2:1.29
	REL8_1_0BETA1:1.29
	REL7_2_8:1.15
	REL7_3_10:1.18
	REL7_4_8:1.25.2.1
	REL8_0_3:1.29
	REL8_0_2:1.29
	REL7_2_7:1.15
	REL7_3_9:1.18
	REL7_4_7:1.25.2.1
	REL8_0_1:1.29
	REL8_0_STABLE:1.29.0.4
	REL8_0_0:1.29.0.2
	REL8_0_0RC5:1.29
	REL8_0_0RC4:1.29
	REL8_0_0RC3:1.29
	REL8_0_0RC2:1.28
	REL8_0_0RC1:1.28
	REL8_0_0BETA5:1.28
	REL8_0_0BETA4:1.28
	REL7_4_6:1.25.2.1
	REL7_3_8:1.18
	REL7_2_6:1.15
	REL8_0_0BETA3:1.28
	REL8_0_0BETA2:1.28
	REL7_2_5:1.15
	REL7_4_5:1.25.2.1
	REL7_3_7:1.18
	REL7_4_4:1.25.2.1
	REL8_0_0BETA1:1.28
	REL7_4_3:1.25.2.1
	REL7_4_2:1.25.2.1
	REL7_3_6:1.18
	REL7_4_1:1.25.2.1
	REL7_3_5:1.18
	REL7_4:1.25.2.1
	REL7_4_RC2:1.25
	REL7_4_STABLE:1.25.0.2
	REL7_4_RC1:1.25
	REL7_4_BETA5:1.25
	REL7_4_BETA4:1.25
	REL7_4_BETA3:1.25
	REL7_4_BETA2:1.23
	WIN32_DEV:1.23.0.2
	REL7_4_BETA1:1.22
	REL7_3_4:1.18
	REL7_3_2:1.18
	REL7_2_4:1.15
	REL7_3_STABLE:1.18.0.2
	REL7_2_3:1.15
	REL7_2_STABLE:1.15.0.2
	REL7_2:1.15
	REL7_2_RC2:1.15
	REL7_2_RC1:1.15
	REL7_2_BETA5:1.15
	REL7_2_BETA4:1.14
	REL7_2_BETA3:1.13
	REL7_2_BETA2:1.13
	REL7_2_BETA1:1.13
	REL7_1_2:1.9
	REL7_1_STABLE:1.9.0.2
	REL7_1_BETA:1.7
	REL7_1_BETA3:1.8
	REL7_1_BETA2:1.8
	REL7_1:1.9
	REL7_0_PATCHES:1.5.0.2
	REL7_0:1.5
	REL6_5_PATCHES:1.3.0.2
	REL6_5:1.3
	REL6_4:1.2.0.2
	release-6-3:1.1;
locks; strict;
comment	@# @;


1.44
date	2010.06.03.14.41.25;	author momjian;	state Exp;
branches;
next	1.43;

1.43
date	2010.06.03.14.39.58;	author momjian;	state Exp;
branches;
next	1.42;

1.42
date	2010.06.01.03.19.36;	author momjian;	state Exp;
branches;
next	1.41;

1.41
date	2010.06.01.02.54.37;	author momjian;	state Exp;
branches;
next	1.40;

1.40
date	2010.06.01.02.35.37;	author momjian;	state Exp;
branches;
next	1.39;

1.39
date	2010.06.01.02.31.36;	author momjian;	state Exp;
branches;
next	1.38;

1.38
date	2010.04.03.07.22.53;	author petere;	state Exp;
branches;
next	1.37;

1.37
date	2008.07.16.01.30.21;	author tgl;	state Exp;
branches;
next	1.36;

1.36
date	2007.08.31.21.33.48;	author momjian;	state Exp;
branches;
next	1.35;

1.35
date	2007.06.06.23.00.35;	author tgl;	state Exp;
branches;
next	1.34;

1.34
date	2007.04.02.03.49.36;	author tgl;	state Exp;
branches;
next	1.33;

1.33
date	2007.01.31.20.56.17;	author momjian;	state Exp;
branches;
next	1.32;

1.32
date	2006.09.16.00.30.13;	author momjian;	state Exp;
branches;
next	1.31;

1.31
date	2006.03.10.19.10.47;	author momjian;	state Exp;
branches;
next	1.30;

1.30
date	2005.10.15.01.47.11;	author neilc;	state Exp;
branches;
next	1.29;

1.29
date	2004.12.30.03.13.56;	author tgl;	state Exp;
branches;
next	1.28;

1.28
date	2004.06.07.04.04.47;	author tgl;	state Exp;
branches;
next	1.27;

1.27
date	2003.11.29.19.51.37;	author pgsql;	state Exp;
branches;
next	1.26;

1.26
date	2003.11.12.22.47.47;	author petere;	state Exp;
branches;
next	1.25;

1.25
date	2003.09.11.21.42.19;	author momjian;	state Exp;
branches
	1.25.2.1;
next	1.24;

1.24
date	2003.08.31.17.32.18;	author petere;	state Exp;
branches;
next	1.23;

1.23
date	2003.08.09.22.50.21;	author tgl;	state Exp;
branches
	1.23.2.1;
next	1.22;

1.22
date	2003.04.13.09.57.35;	author petere;	state Exp;
branches;
next	1.21;

1.21
date	2003.04.10.01.22.44;	author petere;	state Exp;
branches;
next	1.20;

1.20
date	2003.03.25.16.15.36;	author petere;	state Exp;
branches;
next	1.19;

1.19
date	2003.01.19.00.13.28;	author momjian;	state Exp;
branches;
next	1.18;

1.18
date	2002.11.03.01.31.32;	author momjian;	state Exp;
branches;
next	1.17;

1.17
date	2002.09.21.18.32.53;	author petere;	state Exp;
branches;
next	1.16;

1.16
date	2002.07.30.17.34.37;	author tgl;	state Exp;
branches;
next	1.15;

1.15
date	2002.01.07.02.29.11;	author petere;	state Exp;
branches;
next	1.14;

1.14
date	2001.11.21.05.53.41;	author thomas;	state Exp;
branches;
next	1.13;

1.13
date	2001.09.30.16.05.54;	author petere;	state Exp;
branches;
next	1.12;

1.12
date	2001.09.13.15.55.22;	author petere;	state Exp;
branches;
next	1.11;

1.11
date	2001.09.10.21.58.46;	author petere;	state Exp;
branches;
next	1.10;

1.10
date	2001.05.17.21.50.15;	author petere;	state Exp;
branches;
next	1.9;

1.9
date	2001.01.13.23.58.55;	author petere;	state Exp;
branches;
next	1.8;

1.8
date	2000.12.26.00.10.37;	author petere;	state Exp;
branches;
next	1.7;

1.7
date	2000.11.29.20.15.59;	author petere;	state Exp;
branches;
next	1.6;

1.6
date	2000.09.29.20.21.33;	author petere;	state Exp;
branches;
next	1.5;

1.5
date	2000.03.31.03.27.40;	author thomas;	state Exp;
branches;
next	1.4;

1.4
date	99.07.22.15.11.03;	author thomas;	state Exp;
branches;
next	1.3;

1.3
date	98.12.29.02.24.15;	author thomas;	state Exp;
branches;
next	1.2;

1.2
date	98.07.29.06.49.58;	author thomas;	state Exp;
branches;
next	1.1;

1.1
date	98.03.01.08.15.52;	author thomas;	state Exp;
branches;
next	;

1.23.2.1
date	2003.09.07.04.36.41;	author momjian;	state Exp;
branches;
next	;

1.25.2.1
date	2003.11.12.20.05.14;	author petere;	state Exp;
branches;
next	;


desc
@@


1.44
log
@Markup fix.
@
text
@<!-- $PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.43 2010/06/03 14:39:58 momjian Exp $ -->

 <chapter id="extend">
  <title>Extending <acronym>SQL</acronym></title>

  <indexterm zone="extend">
   <primary>extending SQL</primary>
  </indexterm>

  <para>
   In  the  sections  that follow, we will discuss how you
   can extend the <productname>PostgreSQL</productname> 
   <acronym>SQL</acronym> query language by adding:

   <itemizedlist spacing="compact" mark="bullet">
    <listitem>
     <para>
      functions (starting in <xref linkend="xfunc">)
     </para>
    </listitem>
    <listitem>
     <para>
      aggregates (starting in <xref linkend="xaggr">)
     </para>
    </listitem>
    <listitem>
     <para>
      data types (starting in <xref linkend="xtypes">)
     </para>
    </listitem>
    <listitem>
     <para>
      operators (starting in <xref linkend="xoper">)
     </para>
    </listitem>
    <listitem>
     <para>
      operator classes for indexes (starting in <xref linkend="xindex">)
     </para>
    </listitem>
   </itemizedlist>
  </para>

  <sect1 id="extend-how">
   <title>How Extensibility Works</title>

   <para>
    <productname>PostgreSQL</productname> is extensible because its operation  is  
    catalog-driven.   If  you  are familiar with standard 
    relational database systems, you know that  they  store  information
    about  databases,  tables,  columns,  etc., in what are
    commonly known as system catalogs.  (Some systems  call
    this  the data dictionary.)  The catalogs appear to the
    user as tables like any other, but  the  <acronym>DBMS</acronym>  stores
    its  internal  bookkeeping in them.  One key difference
    between <productname>PostgreSQL</productname> and  standard  relational database systems  is
    that <productname>PostgreSQL</productname> stores much more information in its 
    catalogs: not only information about tables and  columns,
    but also information about data types, functions, access
    methods, and so on.  These tables can be  modified  by
    the  user, and since <productname>PostgreSQL</productname> bases its operation 
    on these tables, this means that <productname>PostgreSQL</productname> can  be
    extended   by   users.    By  comparison,  conventional
    database systems can only be extended by changing hardcoded  
    procedures in the source code or by loading modules
    specially written by the <acronym>DBMS</acronym> vendor.
   </para>

   <para>
    The <productname>PostgreSQL</productname> server can moreover
    incorporate user-written code into itself through dynamic loading.
    That is, the user can specify an object code file (e.g., a shared
    library) that implements a new type or function, and
    <productname>PostgreSQL</productname> will load it as required.
    Code written in <acronym>SQL</acronym> is even more trivial to add
    to the server.  This ability to modify its operation <quote>on the
    fly</quote> makes <productname>PostgreSQL</productname> uniquely
    suited for rapid prototyping of new applications and storage
    structures.
   </para>
  </sect1>

  <sect1 id="extend-type-system">
   <title>The <productname>PostgreSQL</productname> Type System</title>

   <indexterm zone="extend-type-system">
    <primary>base type</primary>
   </indexterm>

   <indexterm zone="extend-type-system">
    <primary>data type</primary>
    <secondary>base</secondary>
   </indexterm>

   <indexterm zone="extend-type-system">
    <primary>composite type</primary>
   </indexterm>

   <indexterm zone="extend-type-system">
    <primary>data type</primary>
    <secondary>composite</secondary>
   </indexterm>

   <para>
    <productname>PostgreSQL</productname> data types are divided into base
    types, composite types, domains, and pseudo-types.
   </para>

   <sect2>
    <title>Base Types</title>

    <para>
     Base types are those, like <type>int4</type>, that are
     implemented below the level of the <acronym>SQL</> language
     (typically in a low-level language such as C).  They generally
     correspond to what are often known as abstract data types.
     <productname>PostgreSQL</productname> can only operate on such
     types through functions provided by the user and only understands
     the behavior of such types to the extent that the user describes
     them.  Base types are further subdivided into scalar and array
     types.  For each scalar type, a corresponding array type is
     automatically created that can hold variable-size arrays of that
     scalar type.
    </para>
   </sect2>

   <sect2>
    <title>Composite Types</title>

    <para>
     Composite types, or row types, are created whenever the user
     creates a table. It is also possible to use <xref
     linkend="sql-createtype"> to
     define a <quote>stand-alone</> composite type with no associated
     table.  A composite type is simply a list of types with
     associated field names.  A value of a composite type is a row or
     record of field values.  The user can access the component fields
     from <acronym>SQL</> queries. Refer to <xref linkend="rowtypes">
     for more information on composite types.
    </para>
   </sect2>

   <sect2>
    <title>Domains</title>

    <para>
     A domain is based on a particular base type and for many purposes
     is interchangeable with its base type.  However, a domain can
     have constraints that restrict its valid values to a subset of
     what the underlying base type would allow.
    </para>

    <para>
     Domains can be created using the <acronym>SQL</> command
     <xref linkend="sql-createdomain">.
     Their creation and use is not discussed in this chapter.
    </para>
   </sect2>

   <sect2>
    <title>Pseudo-Types</title>

    <para>
     There are a few <quote>pseudo-types</> for special purposes.
     Pseudo-types cannot appear as columns of tables or attributes of
     composite types, but they can be used to declare the argument and
     result types of functions.  This provides a mechanism within the
     type system to identify special classes of functions.  <xref
     linkend="datatype-pseudotypes-table"> lists the existing
     pseudo-types.
    </para>
   </sect2>

   <sect2 id="extend-types-polymorphic">
    <title>Polymorphic Types</title>

   <indexterm zone="extend-types-polymorphic">
    <primary>polymorphic type</primary>
   </indexterm>

   <indexterm zone="extend-types-polymorphic">
    <primary>polymorphic function</primary>
   </indexterm>

   <indexterm zone="extend-types-polymorphic">
    <primary>type</primary>
    <secondary>polymorphic</secondary>
   </indexterm>

   <indexterm zone="extend-types-polymorphic">
    <primary>function</primary>
    <secondary>polymorphic</secondary>
   </indexterm>

    <para>
     Four pseudo-types of special interest are <type>anyelement</>,
     <type>anyarray</>, <type>anynonarray</>, and <type>anyenum</>,
     which are collectively called <firstterm>polymorphic types</>.
     Any function declared using these types is said to be
     a <firstterm>polymorphic function</>.  A polymorphic function can
     operate on many different data types, with the specific data type(s)
     being determined by the data types actually passed to it in a particular
     call.
    </para>

    <para>
     Polymorphic arguments and results are tied to each other and are resolved
     to a specific data type when a query calling a polymorphic function is
     parsed.  Each position (either argument or return value) declared as
     <type>anyelement</type> is allowed to have any specific actual
     data type, but in any given call they must all be the
     <emphasis>same</emphasis> actual type. Each 
     position declared as <type>anyarray</type> can have any array data type,
     but similarly they must all be the same type. If there are
     positions declared <type>anyarray</type> and others declared
     <type>anyelement</type>, the actual array type in the
     <type>anyarray</type> positions must be an array whose elements are
     the same type appearing in the <type>anyelement</type> positions.
     <type>anynonarray</> is treated exactly the same as <type>anyelement</>,
     but adds the additional constraint that the actual type must not be
     an array type.
     <type>anyenum</> is treated exactly the same as <type>anyelement</>,
     but adds the additional constraint that the actual type must
     be an enum type.
    </para>

    <para>
     Thus, when more than one argument position is declared with a polymorphic
     type, the net effect is that only certain combinations of actual argument
     types are allowed.  For example, a function declared as
     <literal>equal(anyelement, anyelement)</> will take any two input values,
     so long as they are of the same data type.
    </para>

    <para>
     When the return value of a function is declared as a polymorphic type,
     there must be at least one argument position that is also polymorphic,
     and the actual data type supplied as the argument determines the actual
     result type for that call.  For example, if there were not already
     an array subscripting mechanism, one could define a function that
     implements subscripting as <literal>subscript(anyarray, integer)
     returns anyelement</>.  This declaration constrains the actual first
     argument to be an array type, and allows the parser to infer the correct
     result type from the actual first argument's type.  Another example
     is that a function declared as <literal>f(anyarray) returns anyenum</>
     will only accept arrays of enum types.
    </para>

    <para>
     Note that <type>anynonarray</> and <type>anyenum</> do not represent
     separate type variables; they are the same type as
     <type>anyelement</type>, just with an additional constraint.  For
     example, declaring a function as <literal>f(anyelement, anyenum)</>
     is equivalent to declaring it as <literal>f(anyenum, anyenum)</>:
     both actual arguments have to be the same enum type.
    </para>

    <para>
     A variadic function (one taking a variable number of arguments, as in
     <xref linkend="xfunc-sql-variadic-functions">) can be
     polymorphic: this is accomplished by declaring its last parameter as
     <literal>VARIADIC</> <type>anyarray</>.  For purposes of argument
     matching and determining the actual result type, such a function behaves
     the same as if you had written the appropriate number of
     <type>anynonarray</> parameters.
    </para>
   </sect2>
  </sect1>

  &xfunc;
  &xaggr;
  &xtypes;
  &xoper;
  &xindex;

  <sect1 id="extend-Cpp">
   <title>Using C++ for Extensibility</title>

   <indexterm zone="extend-Cpp">
    <primary>C++</primary>
   </indexterm>

   <para>
    It is possible to use a compiler in C++ mode to build
    <productname>PostgreSQL</productname> extensions by following these
    guidelines:

    <itemizedlist>
     <listitem>
      <para>
        All functions accessed by the backend must present a C interface
        to the backend;  these C functions can then call C++ functions.
        For example, <literal>extern C</> linkage is required for
        backend-accessed functions.  This is also necessary for any
        functions that are passed as pointers between the backend and
        C++ code.
      </para>
     </listitem>
     <listitem>
      <para>
       Free memory using the appropriate deallocation method.  For example,
       most backend memory is allocated using <function>palloc()</>, so use
       <function>pfree()</> to free it, i.e. using C++
       <function>delete()</> in such cases will fail.
      </para>
     </listitem>
     <listitem>
      <para>
       Prevent exceptions from propagating into the C code (use a
       catch-all block at the top level of all <literal>extern C</>
       functions).  This is necessary even if the C++ code does not
       throw any exceptions because events like out-of-memory still
       throw exceptions.  Any exceptions must be caught and appropriate
       errors passed back to the C interface.  If possible, compile C++
       with <option>-fno-exceptions</> to eliminate exceptions entirely;
       in such cases, you must check for failures in your C++ code, e.g.
       check for NULL returned by <function>new()</>.
      </para>
     </listitem>
     <listitem>
      <para>
       If calling backend functions from C++ code, be sure that the
       C++ call stack contains only plain old data structure
       (<acronym>POD</>).  This is necessary because backend errors
       generate a distant <function>longjump()</> that does not properly
       unroll a C++ call stack with non-POD objects.
      </para>
     </listitem>
    </itemizedlist>
   </para>

   <para>
    In summary, it is best to place C++ code behind a wall of
    <literal>extern C</> functions that interface to the backend,
    and avoid exception, memory, and call stack leakage.
   </para>
  </sect1>

 </chapter>
@


1.43
log
@Document use of C++ for extension use.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.42 2010/06/01 03:19:36 momjian Exp $ -->
d305 1
@


1.42
log
@Comment out C++ docs for later user.  Tone down C++ compatibility in 9.0
release notes.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.41 2010/06/01 02:54:37 momjian Exp $ -->
a275 2
<!-- Use this someday when C++ is easier to use. bjm 2010-05-31

d285 2
a286 2
    <productname>PostgreSQL</productname> extensions;  you must simply
    follow the standard methods for dynamically linking to C executables:
d291 6
a296 4
        Use <literal>extern C</> linkage for all functions that must
        be accessible by <function>dlopen()</>.  This is also necessary
        for any functions that might be passed as pointers between
        the backend and C++ code.
d301 4
a304 4
       Use <function>palloc()</> to allocate any memory that might be
       freed by the backend C code (don't pass <function>new()</>-allocated
       memory).
      </para>
d308 9
a316 2
       Use <function>pfree()</> to free memory allocated by the backend
       C code (do not use <function>delete()</> for such cases).
d321 5
a325 3
       Prevent exceptions from propagating into the C code (use a
       catch-all block at the top level of all <literal>extern C</>
       functions).
d331 5
a336 1
-->
@


1.41
log
@Mention palloc/pfree for C++ memory allocation in docs.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.40 2010/06/01 02:35:37 momjian Exp $ -->
d276 2
d323 1
@


1.40
log
@Fix SGML markup for tag title.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.39 2010/06/01 02:31:36 momjian Exp $ -->
d299 1
a299 1
       Use <function>malloc()</> to allocate any memory that might be
d306 1
a306 1
       Use <function>free()</> to free memory allocated by the backend
@


1.39
log
@Add documentation section "Using C++ for Extensibility".

Craig Ringer
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.38 2010/04/03 07:22:53 petere Exp $ -->
d276 1
a276 1
  <sect1 id="extend-how">
@


1.38
log
@Remove unnecessary xref endterm attributes and title ids

The endterm attribute is mainly useful when the toolchain does not support
automatic link target text generation for a particular situation.  In  the
past, this was required by the man page tools for all reference page links,
but that is no longer the case, and it now actually gets in the way of
proper automatic link text generation.  The only remaining use cases are
currently xrefs to refsects.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.37 2008/07/16 01:30:21 tgl Exp $ -->
d276 46
@


1.37
log
@Support "variadic" functions, which can accept a variable number of arguments
so long as all the trailing arguments are of the same (non-array) type.
The function receives them as a single array argument (which is why they
have to all be the same type).

It might be useful to extend this facility to aggregates, but this patch
doesn't do that.

This patch imposes a noticeable slowdown on function lookup --- a follow-on
patch will fix that by adding a redundant column to pg_proc.

Pavel Stehule
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.36 2007/08/31 21:33:48 momjian Exp $ -->
d133 1
a133 1
     linkend="sql-createtype" endterm="sql-createtype-title"> to
d155 1
a155 1
     <xref linkend="sql-createdomain" endterm="sql-createdomain-title">.
@


1.36
log
@Only use SGML indexterm "zone" when we want to get the entire section.

Some alignment cleanups.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.35 2007/06/06 23:00:35 tgl Exp $ -->
d257 10
@


1.35
log
@Fix up text concatenation so that it accepts all the reasonable cases that
were accepted by prior Postgres releases.  This takes care of the loose end
left by the preceding patch to downgrade implicit casts-to-text.  To avoid
breaking desirable behavior for array concatenation, introduce a new
polymorphic pseudo-type "anynonarray" --- the added concatenation operators
are actually text || anynonarray and anynonarray || text.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.34 2007/04/02 03:49:36 tgl Exp $ -->
d6 3
a8 3
   <indexterm zone="extend">
    <primary>extending SQL</primary>
   </indexterm>
@


1.34
log
@Support enum data types.  Along the way, use macros for the values of
pg_type.typtype whereever practical.  Tom Dunstan, with some kibitzing
from Tom Lane.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.33 2007/01/31 20:56:17 momjian Exp $ -->
d196 2
a197 2
     Three pseudo-types of special interest are <type>anyelement</>,
     <type>anyarray</>, and <type>anyenum</>,
d219 3
d248 9
@


1.33
log
@Update documentation on may/can/might:

Standard English uses "may", "can", and "might" in different ways:

        may - permission, "You may borrow my rake."

        can - ability, "I can lift that log."

        might - possibility, "It might rain today."

Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice.  Similarly, "It may crash" is better stated, "It might crash".

Also update two error messages mentioned in the documenation to match.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.32 2006/09/16 00:30:13 momjian Exp $ -->
d196 4
a199 3
     Two pseudo-types of special interest are <type>anyelement</> and
     <type>anyarray</>, which are collectively called <firstterm>polymorphic
     types</>.  Any function declared using these types is said to be
d219 3
d241 3
a243 1
     result type from the actual first argument's type.
@


1.32
log
@Remove emacs info from footer of SGML files.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.31 2006/03/10 19:10:47 momjian Exp $ -->
d148 1
a148 1
     is interchangeable with its base type.  However, a domain may
@


1.31
log
@Make $PostgreSQL CVS tags consistent for SGML files.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/advanced.sgml,v 1.49 2005/04/09 03:52:43 momjian Exp $ -->
a248 17

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->
@


1.30
log
@Merge some user-submitted suggestions for improvement into the
documentation. Mostly add some <xref>s, fix a few typos, and
document that zlib is required in the installation docs.
@
text
@d1 1
a1 3
<!--
$PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.29 2004/12/30 03:13:56 tgl Exp $
-->
@


1.29
log
@More updates and copy-editing.  Rearrange order of sections a little bit
to put more widely useful info before less widely useful info.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.28 2004/06/07 04:04:47 tgl Exp $
d134 8
a141 6
     creates a table; it's also possible to define a
     <quote>stand-alone</> composite type with no associated table.  A
     composite type is simply a list of base types with associated
     field names.  A value of a composite type is a row or record of
     field values.  The user can access the component fields from
     <acronym>SQL</> queries.
@


1.28
log
@Some preliminary documentation for composite-type stuff.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/extend.sgml,v 1.27 2003/11/29 19:51:37 pgsql Exp $
d155 2
a156 2
     <command>CREATE DOMAIN</command>.  Their creation and use is not
     discussed in this chapter.
d224 1
a224 1
     <literal>foo(anyelement, anyelement)</> will take any two input values,
@


1.27
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d2 1
a2 1
$PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/extend.sgml,v 1.26 2003/11/12 22:47:47 petere Exp $
d154 1
a154 1
     Domains can be created using the <acronym>SQL</> commands
@


1.26
log
@Documentation cleanup
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/extend.sgml,v 1.25 2003/09/11 21:42:19 momjian Exp $
@


1.25
log
@This patch fixes a few missed GUC variables that were still upper case,
makes a few more small improvements to runtime.sgml, and makes some SGML
conventions more consistent.

Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/extend.sgml,v 1.24 2003/08/31 17:32:18 petere Exp $
d108 1
a108 1
    types, composite types, domain types, and pseudo-types.
d111 2
a112 22
   <para>
    Base  types  are those, like <type>int4</type>, that are implemented
    below the level of the  <acronym>SQL</> language (typically in a low-level
    language such as C).  They generally correspond  to
    what are often known as abstract data types.
    <productname>PostgreSQL</productname>
    can only operate on such types through functions provided
    by  the  user and only understands the behavior of such
    types to the extent that the user describes them.  Base types are
    further subdivided into scalar and array types.  For each scalar type,
    a corresponding array type is automatically created that can hold
    variable-size arrays of that scalar type.
   </para>

   <para>
    Composite  types, or row types,  are  created whenever the user creates a
    table; it's also possible to define a <quote>stand-alone</> composite
    type with no associated table.  A composite type is simply a list of
    base types with associated field names.  A value of a composite type
    is a row or record of field values.  The user can access the component
    fields from <acronym>SQL</> queries.
   </para>
d114 59
a172 17
   <para>
    A domain type is based on a particular base
    type and for many purposes is interchangeable with its base type.
    However, a domain may have constraints that restrict its valid values
    to a subset of what the underlying base type would allow.  Domains can
    be created by simple <acronym>SQL</> commands.
   </para>

   <para>
    Finally, there are a few <quote>pseudo-types</> for special purposes.
    Pseudo-types cannot appear as fields of tables or composite types, but
    they can be used to declare the argument and result types of functions.
    This provides a mechanism within the type system to identify special
    classes of functions.  <xref
    linkend="datatype-pseudotypes-table"> lists the existing
    pseudo-types.
   </para>
d175 1
a175 1
    <title>Polymorphic Types and Functions</title>
@


1.25.2.1
log
@Documentation cleanup
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/extend.sgml,v 1.25 2003/09/11 21:42:19 momjian Exp $
d108 1
a108 1
    types, composite types, domains, and pseudo-types.
d111 22
a132 2
   <sect2>
    <title>Base Types</title>
d134 17
a150 59
    <para>
     Base types are those, like <type>int4</type>, that are
     implemented below the level of the <acronym>SQL</> language
     (typically in a low-level language such as C).  They generally
     correspond to what are often known as abstract data types.
     <productname>PostgreSQL</productname> can only operate on such
     types through functions provided by the user and only understands
     the behavior of such types to the extent that the user describes
     them.  Base types are further subdivided into scalar and array
     types.  For each scalar type, a corresponding array type is
     automatically created that can hold variable-size arrays of that
     scalar type.
    </para>
   </sect2>

   <sect2>
    <title>Composite Types</title>

    <para>
     Composite types, or row types, are created whenever the user
     creates a table; it's also possible to define a
     <quote>stand-alone</> composite type with no associated table.  A
     composite type is simply a list of base types with associated
     field names.  A value of a composite type is a row or record of
     field values.  The user can access the component fields from
     <acronym>SQL</> queries.
    </para>
   </sect2>

   <sect2>
    <title>Domains</title>

    <para>
     A domain is based on a particular base type and for many purposes
     is interchangeable with its base type.  However, a domain may
     have constraints that restrict its valid values to a subset of
     what the underlying base type would allow.
    </para>

    <para>
     Domains can be created using the <acronym>SQL</> commands
     <command>CREATE DOMAIN</command>.  Their creation and use is not
     discussed in this chapter.
    </para>
   </sect2>

   <sect2>
    <title>Pseudo-Types</title>

    <para>
     There are a few <quote>pseudo-types</> for special purposes.
     Pseudo-types cannot appear as columns of tables or attributes of
     composite types, but they can be used to declare the argument and
     result types of functions.  This provides a mechanism within the
     type system to identify special classes of functions.  <xref
     linkend="datatype-pseudotypes-table"> lists the existing
     pseudo-types.
    </para>
   </sect2>
d153 1
a153 1
    <title>Polymorphic Types</title>
@


1.24
log
@Add/edit index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/extend.sgml,v 1.23 2003/08/09 22:50:21 tgl Exp $
d72 10
a81 8
    The PostgreSQL server can moreover incorporate user-written code into
    itself through dynamic loading.  That is, the user  can
    specify  an  object code file (e.g., a shared library) that implements a new type or  function,
    and <productname>PostgreSQL</productname> will load it as required.  Code written 
    in <acronym>SQL</acronym> is even more trivial to add to the  server.
    This ability to modify its operation <quote>on the fly</quote> makes
    <productname>PostgreSQL</productname> uniquely suited for rapid prototyping  of  new
    applications and storage structures.
@


1.23
log
@Update docs for 7.4 array features and polymorphic functions.
This is Joe Conway's patch of 7-Aug plus further editorializing
of my own.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/extend.sgml,v 1.22 2003/04/13 09:57:35 petere Exp $
d83 1
a83 1
  <sect1 id="type-system">
d86 11
a96 3
   <indexterm zone="type-system">
    <primary>extending SQL</primary>
    <secondary>types</secondary>
d99 3
a101 2
   <indexterm zone="type-system">
    <primary>data types</primary>
d150 1
a150 1
   <sect2 id="types-polymorphic">
d153 11
a163 2
   <indexterm>
    <primary>polymorphic types</primary>
d166 3
a168 2
   <indexterm>
    <primary>polymorphic functions</primary>
@


1.23.2.1
log
@Update this branch to match CVS head, includes WIN32 improvements.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/extend.sgml,v 1.24 2003/08/31 17:32:18 petere Exp $
d83 1
a83 1
  <sect1 id="extend-type-system">
d86 3
a88 11
   <indexterm zone="extend-type-system">
    <primary>base type</primary>
   </indexterm>

   <indexterm zone="extend-type-system">
    <primary>data type</primary>
    <secondary>base</secondary>
   </indexterm>

   <indexterm zone="extend-type-system">
    <primary>composite type</primary>
d91 2
a92 3
   <indexterm zone="extend-type-system">
    <primary>data type</primary>
    <secondary>composite</secondary>
d141 1
a141 1
   <sect2 id="extend-types-polymorphic">
d144 2
a145 11
   <indexterm zone="extend-types-polymorphic">
    <primary>polymorphic type</primary>
   </indexterm>

   <indexterm zone="extend-types-polymorphic">
    <primary>polymorphic function</primary>
   </indexterm>

   <indexterm zone="extend-types-polymorphic">
    <primary>type</primary>
    <secondary>polymorphic</secondary>
d148 2
a149 3
   <indexterm zone="extend-types-polymorphic">
    <primary>function</primary>
    <secondary>polymorphic</secondary>
@


1.22
log
@Integrate the operator class section into the comprehensive extending SQL
chapter as well.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/extend.sgml,v 1.21 2003/04/10 01:22:44 petere Exp $
d25 5
d40 1
a40 1
      aggregates (starting in <xref linkend="xaggr">)
d55 1
a55 1
    this  the data dictionary).  The catalogs appear to the
d96 5
a100 1
    Data types are divided into base types and composite  types.
d102 5
a106 3
    in a language such as C.  They generally correspond  to
    what are often known as abstract data types.  <productname>PostgreSQL</productname>
    can only operate on such types through methods provided
d108 21
a128 5
    types to the extent that the user describes them.  
    Composite  types  are  created whenever the user creates a
    table.  The
    user can <quote>look inside</quote> at the attributes of these types
    from the query language.
d130 67
d200 1
a202 1
  &xaggr;
@


1.21
log
@In an effort to reduce the total number of chapters, combine the small
chapters on extending types, operators, and aggregates into the extending
functions chapter.  Move the information on how to call table functions
into the queries chapter.  Remove some outdated information that is
already present in a better form in other parts of the documentation.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/extend.sgml,v 1.20 2003/03/25 16:15:36 petere Exp $
d109 1
@


1.20
log
@Merge documentation into one book.  (Build with "make html".)  Replace
vague cross-references with real links.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/extend.sgml,v 1.19 2003/01/19 00:13:28 momjian Exp $
d6 1
a6 1
  <title>Extending <acronym>SQL</acronym>: An Overview</title>
d20 1
a20 1
      functions
d25 1
a25 1
      data types
d30 1
a30 1
      operators
d35 1
a35 1
      aggregates
d47 1
a47 1
    relational systems, you know that  they  store  information
d53 1
a53 1
    between <productname>PostgreSQL</productname> and  standard  relational  systems  is
d55 2
a56 2
    catalogs -- not only information about tables and  columns,
    but also information about its types, functions, access
d58 1
a58 1
    the  user, and since <productname>PostgreSQL</productname> bases its internal operation 
d62 1
a62 1
    procedures within the <acronym>DBMS</acronym> or by loading modules
d67 1
a67 2
    <productname>PostgreSQL</productname> is also unlike most  other  data  managers  in
    that  the server can incorporate user-written code into
d69 1
a69 1
    specify  an  object code file (e.g., a shared library) that implements a new type or  function 
d91 1
a91 3
    The <productname>PostgreSQL</productname> type system
    can be broken down in several ways.
    Types are divided into base types and composite  types.
d94 1
a94 1
    what are often known as <firstterm>abstract data types</firstterm>; <productname>PostgreSQL</productname>
d99 1
a99 7
    table.
   </para>

   <para>
    <productname>PostgreSQL</productname>  stores  these  types
    in only one way (within the
    file that stores all rows of a table)  but  the
d101 1
a101 9
    from the query language and optimize their retrieval by
    (for example) defining indexes on the attributes.
    <productname>PostgreSQL</productname>  base  types are further
    divided into built-in
    types and user-defined  types.   Built-in  types  (like
    <type>int4</type>)  are  those  that  are  compiled
    into the system.
    User-defined types are those created by the user in the
    manner to be described later.
d105 4
a108 2
  <sect1 id="pg-system-catalogs">
   <title>About the <productname>PostgreSQL</productname> System Catalogs</title>
a109 156
   <indexterm zone="pg-system-catalogs">
    <primary>catalogs</primary>
   </indexterm>

   <para>
    Having  introduced the basic extensibility concepts, we
    can now take a look at how the  catalogs  are  actually
    laid  out.  You can skip this section for now, but some
    later sections will  be  incomprehensible  without  the
    information  given  here,  so  mark this page for later
    reference.
    All system catalogs have names  that  begin  with
    <literal>pg_</literal>.
    The  following  tables contain information that may be
    useful to the end user.  (There are many  other  system
    catalogs,  but there should rarely be a reason to query
    them directly.)

    <table tocentry="1">
     <title>PostgreSQL System Catalogs</title>
     <titleabbrev>Catalogs</titleabbrev>
     <tgroup cols="2">
      <thead>
       <row>
	<entry>Catalog Name</entry>
	<entry>Description</entry>
       </row>
      </thead>
      <tbody>
       <row>
	<entry><structname>pg_database</></entry>
	<entry> databases</entry>
       </row>
       <row>
	<entry><structname>pg_class</></entry>
	<entry> tables</entry>
       </row>
       <row>
	<entry><structname>pg_attribute</></entry>
	<entry> table columns</entry>
       </row>
       <row>
	<entry><structname>pg_index</></entry>
	<entry> indexes</entry>
       </row>
       <row>
	<entry><structname>pg_proc</></entry>
	<entry> procedures/functions </entry>
       </row>
       <row>
	<entry><structname>pg_type</></entry>
	<entry> data types (both base and complex)</entry>
       </row>
       <row>
	<entry><structname>pg_operator</></entry>
	<entry> operators</entry>
       </row>
       <row>
	<entry><structname>pg_aggregate</></entry>
	<entry> aggregate functions</entry>
       </row>
       <row>
	<entry><structname>pg_am</></entry>
	<entry> access methods</entry>
       </row>
       <row>
	<entry><structname>pg_amop</></entry>
	<entry> access method operators</entry>
       </row>
       <row>
	<entry><structname>pg_amproc</></entry>
	<entry> access method support functions</entry>
       </row>
       <row>
	<entry><structname>pg_opclass</></entry>
	<entry> access method operator classes</entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>

   <para>
    <figure float="1" id="EXTEND-CATALOGS">
     <title>The major <productname>PostgreSQL</productname> system catalogs</title>
     <mediaobject>
      <imageobject>
       <imagedata fileref="catalogs" align="center">
      </imageobject>
     </mediaobject>
    </figure>

    <xref linkend="catalogs"> gives a more detailed explanation of these
    catalogs and their columns.  However,
    <xref linkend="EXTEND-CATALOGS">
    shows the major entities and their  relationships
    in  the system catalogs.  (Columns that do not refer
    to other entities are not shown unless they are part of
    a primary key.)
    This diagram is more or less incomprehensible until you
    actually start looking at the contents of the  catalogs
    and  see  how  they relate to each other.  For now, the
    main things to take away from this diagram are as  follows:
     
    <itemizedlist spacing="compact" mark="bullet">
     <listitem>
      <para>
       In  several of the sections that follow, we will
       present various join queries on the system 
       catalogs  that display information we need to extend
       the system.  Looking at this diagram should make
       some  of  these  join  queries  (which are often
       three- or four-way joins)  more  understandable,
       because  you  will  be  able  to  see  that  the
       columns used in the queries form foreign keys
       in other tables.
      </para>
     </listitem>
     <listitem>
      <para>
       Many  different  features  (tables, columns,
       functions,  types,  access  methods,  etc.)  are
       tightly  integrated  in  this  schema.  A simple
       create command may modify many  of  these  catalogs.
      </para>
     </listitem>
     <listitem>
      <para>
       Types and procedures
       are central to the schema.

       <note>
	<para>
	 We  use  the words <firstterm>procedure</firstterm>
	 and <firstterm>function</firstterm> more or less interchangeably.
	</para>
       </note>

       Nearly  every catalog contains some reference to
       rows in one or both of these tables.   For
       example,  <productname>PostgreSQL</productname>  frequently  uses type 
       signatures (e.g.,  of  functions  and  operators)  to
       identify unique rows of other catalogs.
      </para>
     </listitem>
     <listitem>
      <para>
       There are many columns and relationships that
       have obvious meanings, but there are many  
       (particularly  those  that  have  to  do with access
       methods) that do not.
      </para>
     </listitem>
    </itemizedlist>
   </para>
  </sect1>
@


1.19
log
@This patch includes a lot of minor cleanups to the SGML documentation,
including:

- replacing all the appropriate usages of <citetitle>PostgreSQL
...</citetitle> with &cite-user;, &cite-admin;, and so on

- fix an omission in the EXECUTE documentation

- add some more text to the EXPLAIN documentation

- improve the PL/PgSQL RETURN NEXT documentation (more work to do here)

- minor markup fixes


Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/extend.sgml,v 1.18 2002/11/03 01:31:32 momjian Exp $
d217 1
a217 1
    The &cite-developer; gives a more detailed explanation of these
@


1.18
log
@This patch adds a couple of extra index entries and removes some
out-of-date text about multibyte encoding (which is now always
included).

Oliver Elphick
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/extend.sgml,v 1.17 2002/09/21 18:32:53 petere Exp $
d217 2
a218 2
    The <citetitle>Developer's Guide</citetitle> gives a more detailed  explanation
    of  these catalogs and their columns.  However,
@


1.17
log
@Add more appropriate markup.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/extend.sgml,v 1.16 2002/07/30 17:34:37 tgl Exp $
d8 4
d82 9
d124 4
@


1.16
log
@Replace ad-hoc insertions into pg_opclass and friends with CREATE
OPERATOR CLASS commands.  Further tweaking of documentation for same.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.15 2002/01/07 02:29:11 petere Exp $
d138 1
a138 1
	<entry>pg_database</entry>
d142 1
a142 1
	<entry>pg_class</entry>
d146 1
a146 1
	<entry>pg_attribute</entry>
d150 1
a150 1
	<entry>pg_index</entry>
d154 1
a154 1
	<entry>pg_proc</entry>
d158 1
a158 1
	<entry>pg_type</entry>
d162 1
a162 1
	<entry>pg_operator</entry>
d166 1
a166 1
	<entry>pg_aggregate</entry>
d170 1
a170 1
	<entry>pg_am</entry>
d174 1
a174 1
	<entry>pg_amop</entry>
d178 1
a178 1
	<entry>pg_amproc</entry>
d182 1
a182 1
	<entry>pg_opclass</entry>
@


1.15
log
@Editorial review
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.14 2001/11/21 05:53:41 thomas Exp $
d258 1
a258 5
       methods) that do not.  The relationships between
       <classname>pg_am</>, <classname>pg_amop</>, <classname>pg_amproc</>, <classname>pg_operator</>, and
       <classname>pg_opclass</> are particularly hard  to  understand
       and  will  be described in depth (in <xref linkend="xindex">)
       after we have discussed basic extensions.
@


1.14
log
@Deprecate 'current' for date/time input.
Fix up references to "PostgreSQL" rather than "Postgres". Was roughly
 evenly split between the two before. ref/ files not yet done.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.13 2001/09/30 16:05:54 petere Exp $
d21 1
a21 1
      types
d59 1
a59 1
    specially-written by the <acronym>DBMS</acronym> vendor.
d66 1
a66 2
    specify  an  object code file (e.g., a compiled .o file
    or shared library) that implements a new type or  function 
d68 1
a68 1
    in <acronym>SQL</acronym> are even more trivial to add to the  server.
d82 2
a83 2
    Base  types  are those, like <firstterm>int4</firstterm>, that are implemented
    in a language such as <productname>C</productname>.  They generally correspond  to
d89 1
a89 1
    table.  EMP is an example of a composite  type.   
d102 1
a102 1
    <firstterm>int4</firstterm>)  are  those  that  are  compiled
d105 1
a105 1
    manner to be described below.
d120 1
a120 1
    <firstterm>pg_</firstterm>.
d151 1
a151 1
	<entry> secondary indexes</entry>
d155 1
a155 1
	<entry> procedures (both C and SQL)</entry>
d159 1
a159 1
	<entry> types (both base and complex)</entry>
d167 1
a167 1
	<entry> aggregates and aggregate functions</entry>
d200 1
a200 1
    The Reference Manual gives a more detailed  explanation
d259 3
a261 4
       pg_am,   pg_amop,   pg_amproc,  pg_operator  and
       pg_opclass are particularly hard  to  understand
       and  will  be described in depth (in the section
       on interfacing types and operators  to  indexes)
@


1.13
log
@Use <mediaobject> instead of <graphic> for forward compatibility.  Be more
flexible about the extension of the graphic files, allow for other formats
in print output.  (Generating these formats is not implemented yet.)
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.12 2001/09/13 15:55:22 petere Exp $
d10 1
a10 1
   can extend the <productname>Postgres</productname> 
d41 1
a41 1
    <productname>Postgres</productname> is extensible because its operation  is  
d49 2
a50 2
    between <productname>Postgres</productname> and  standard  relational  systems  is
    that <productname>Postgres</productname> stores much more information in its 
d54 2
a55 2
    the  user, and since <productname>Postgres</productname> bases its internal operation 
    on these tables, this means that <productname>Postgres</productname> can  be
d63 1
a63 1
    <productname>Postgres</productname> is also unlike most  other  data  managers  in
d68 1
a68 1
    and <productname>Postgres</productname> will load it as required.  Code written 
d71 1
a71 1
    <productname>Postgres</productname> uniquely suited for rapid prototyping  of  new
d77 1
a77 1
   <title>The <productname>Postgres</productname> Type System</title>
d80 1
a80 1
    The <productname>Postgres</productname> type system
d85 1
a85 1
    what are often known as <firstterm>abstract data types</firstterm>; <productname>Postgres</productname>
d94 1
a94 1
    <productname>Postgres</productname>  stores  these  types
d100 1
a100 1
    <productname>Postgres</productname>  base  types are further
d111 1
a111 1
   <title>About the <productname>Postgres</productname> System Catalogs</title>
d128 1
a128 1
     <title>Postgres System Catalogs</title>
d193 1
a193 1
     <title>The major <productname>Postgres</productname> system catalogs</title>
d249 1
a249 1
       example,  <productname>Postgres</productname>  frequently  uses type 
@


1.12
log
@Replace ASCII-quotes with proper markup.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.11 2001/09/10 21:58:46 petere Exp $
d194 5
a198 1
     <graphic fileref="catalogs.gif" format="GIF" align="center"></graphic>
@


1.11
log
@Markup and spell-check run over Programmer's Guide (rather incomplete still).
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.10 2001/05/17 21:50:15 petere Exp $
d70 1
a70 1
    This ability to modify its operation "on the fly" makes
d85 1
a85 1
    what are often known as "abstract data types"; <productname>Postgres</productname>
d97 1
a97 1
    user can "look inside" at the attributes of these types
@


1.10
log
@Change "indices" to "indexes", per OED.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.9 2001/01/13 23:58:55 petere Exp $
d239 1
a239 1
	 and <firstterm>function</firstterm> more or less interchangably.
@


1.9
log
@Terminology cleanup: class -> table, instance -> row, attribute -> column,
etc.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.8 2000/12/26 00:10:37 petere Exp $
d99 1
a99 1
    (for example) defining indices on the attributes.
d152 1
a152 1
	<entry> secondary indices</entry>
d259 1
a259 1
       on interfacing types and operators  to  indices)
@


1.8
log
@Fix some cross reference links.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.7 2000/11/29 20:15:59 petere Exp $
d47 1
a47 1
    user as classes, like any other, but  the  <acronym>DBMS</acronym>  stores
d53 1
a53 1
    methods, and so on.  These classes can be  modified  by
d55 1
a55 1
    on these classes, this means that <productname>Postgres</productname> can  be
d90 1
a90 1
    class.  EMP is an example of a composite  type.   
d96 1
a96 1
    file that stores all instances of the  class)  but  the
d122 1
a122 1
    The  following  classes contain information that may be
d144 1
a144 1
	<entry> classes</entry>
d148 1
a148 1
	<entry> class attributes</entry>
d198 1
a198 1
    of  these catalogs and their attributes.  However,
d201 1
a201 1
    in  the system catalogs.  (Attributes that do not refer
d219 2
a220 2
       attributes used in the queries form foreign keys
       in other classes.
d225 1
a225 1
       Many  different  features  (classes, attributes,
d244 1
a244 1
       instances in one or both of these classes.   For
d247 1
a247 1
       identify unique instances of other catalogs.
d252 1
a252 1
       There are many attributes and relationships that
@


1.7
log
@Rewrite system catalog documentation man page in DocBook with more recent
information.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.6 2000/09/29 20:21:33 petere Exp $
d199 1
a199 1
    <xref endterm="EXTEND-CATALOGS" linkend="EXTEND-CATALOGS">
@


1.6
log
@Add `id' attributes to all `chapter' and `sect1' tags, to generate useful
names for the HTML files (e.g., not x4856.htm).
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.5 2000/03/31 03:27:40 thomas Exp $
d110 1
a110 1
  <sect1 id="system-catalogs">
@


1.5
log
@Minor markup changes. Refer to (".../catalog") in the emacs hints.
@
text
@d2 1
a2 1
$Header$
d37 1
a37 1
  <sect1>
d76 1
a76 1
  <sect1>
d110 1
a110 1
  <sect1>
@


1.4
log
@Complete merge of all old man page information.
lisp.sgml is a placeholder for Eric Marsden's upcoming contribution.
catalogs.sgml is not yet marked up or integrated.
 It should perhaps become an appendix.
@
text
@d1 4
d270 1
a270 1
mode: sgml
d280 1
a280 1
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
@


1.3
log
@Clean up to ensure tag completion as required by the newest versions
 of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@@michvhf.com>.
@
text
@d1 2
a2 2
<Chapter Id="extend">
<Title>Extending <Acronym>SQL</Acronym>: An Overview</Title>
d4 8
a11 6
<Para>
     In  the  sections  that follow, we will discuss how you
     can extend the <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> query language by adding:
<ItemizedList Mark="bullet" Spacing="compact">
<ListItem>
<Para>
d13 4
a16 4
</Para>
</ListItem>
<ListItem>
<Para>
d18 4
a21 4
</Para>
</ListItem>
<ListItem>
<Para>
d23 4
a26 4
</Para>
</ListItem>
<ListItem>
<Para>
d28 176
a203 169
</Para>
</ListItem>
</ItemizedList>
</Para>

<Sect1>
<Title>How Extensibility Works</Title>

<Para>
     <ProductName>Postgres</ProductName> is extensible because its operation  is  
     catalog-driven.   If  you  are familiar with standard 
     relational systems, you know that  they  store  information
     about  databases,  tables,  columns,  etc., in what are
     commonly known as system catalogs.  (Some systems  call
     this  the data dictionary).  The catalogs appear to the
     user as classes, like any other, but  the  <Acronym>DBMS</Acronym>  stores
     its  internal  bookkeeping in them.  One key difference
     between <ProductName>Postgres</ProductName> and  standard  relational  systems  is
     that <ProductName>Postgres</ProductName> stores much more information in its 
     catalogs -- not only information about tables and  columns,
     but also information about its types, functions, access
     methods, and so on.  These classes can be  modified  by
     the  user, and since <ProductName>Postgres</ProductName> bases its internal operation 
     on these classes, this means that <ProductName>Postgres</ProductName> can  be
     extended   by   users.    By  comparison,  conventional
     database systems can only be extended by changing hardcoded  
     procedures within the <Acronym>DBMS</Acronym> or by loading modules
     specially-written by the <Acronym>DBMS</Acronym> vendor.
</Para>
<Para>
     <ProductName>Postgres</ProductName> is also unlike most  other  data  managers  in
     that  the server can incorporate user-written code into
     itself through dynamic loading.  That is, the user  can
     specify  an  object code file (e.g., a compiled .o file
     or shared library) that implements a new type or  function 
     and <ProductName>Postgres</ProductName> will load it as required.  Code written 
     in <Acronym>SQL</Acronym> are even more trivial to add to the  server.
     This ability to modify its operation "on the fly" makes
     <ProductName>Postgres</ProductName> uniquely suited for rapid prototyping  of  new
     applications and storage structures.
</Para>
</Sect1>

<Sect1>
<Title>The <ProductName>Postgres</ProductName> Type System</Title>

<Para>
     The  <ProductName>Postgres</ProductName> type system can be broken down in several ways.
     Types are divided into base types and composite  types.
     Base  types  are those, like <FirstTerm>int4</FirstTerm>, that are implemented
     in a language such as <ProductName>C</ProductName>.  They generally correspond  to
     what are often known as "abstract data types"; <ProductName>Postgres</ProductName>
     can only operate on such types through methods provided
     by  the  user and only understands the behavior of such
     types to the extent that the user describes them.  
     Composite  types  are  created whenever the user creates a
     class.  EMP is an example of a composite  type.   
</Para>
<Para>
     <ProductName>Postgres</ProductName>  stores  these  types  in only one way (within the
     file that stores all instances of the  class)  but  the
     user can "look inside" at the attributes of these types
     from the query language and optimize their retrieval by
     (for example) defining indices on the attributes.
     <ProductName>Postgres</ProductName>  base  types are further divided into built-in
     types and user-defined  types.   Built-in  types  (like
     <FirstTerm>int4</FirstTerm>)  are  those  that  are  compiled into the system.
     User-defined types are those created by the user in the
     manner to be described below.
</Para>
</Sect1>

<Sect1>
<Title>About the <ProductName>Postgres</ProductName> System Catalogs</Title>

<Para>
     Having  introduced the basic extensibility concepts, we
     can now take a look at how the  catalogs  are  actually
     laid  out.  You can skip this section for now, but some
     later sections will  be  incomprehensible  without  the
     information  given  here,  so  mark this page for later
     reference.
     All system catalogs have names  that  begin  with  <FirstTerm>pg_</FirstTerm>.
     The  following  classes contain information that may be
     useful to the end user.  (There are many  other  system
     catalogs,  but there should rarely be a reason to query
     them directly.)

<TABLE TOCENTRY="1">
<TITLE>Postgres System Catalogs</TITLE>
<TITLEABBREV>Catalogs</TITLEABBREV>
<TGROUP COLS="2">
<THEAD>
<ROW>
<ENTRY>Catalog Name</ENTRY>
<ENTRY>Description</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY>pg_database</ENTRY>
<ENTRY> databases</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_class</ENTRY>
<ENTRY> classes</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_attribute</ENTRY>
<ENTRY> class attributes</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_index</ENTRY>
<ENTRY> secondary indices</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_proc</ENTRY>
<ENTRY> procedures (both C and SQL)</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_type</ENTRY>
<ENTRY> types (both base and complex)</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_operator</ENTRY>
<ENTRY> operators</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_aggregate</ENTRY>
<ENTRY> aggregates and aggregate functions</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_am</ENTRY>
<ENTRY> access methods</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_amop</ENTRY>
<ENTRY> access method operators</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_amproc</ENTRY>
<ENTRY> access method support functions</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_opclass</ENTRY>
<ENTRY> access method operator classes</ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>

<Para>
<Figure Id="EXTEND-CATALOGS" Float="1">
<Title>The major <ProductName>Postgres</ProductName> system catalogs</Title>
<Graphic Align="center" FileRef="catalogs.gif" Format="GIF"></Graphic>
</Figure>

     The Reference Manual gives a more detailed  explanation
     of  these catalogs and their attributes.  However,
<XRef LinkEnd="EXTEND-CATALOGS" EndTerm="EXTEND-CATALOGS">
     shows the major entities and their  relationships
     in  the system catalogs.  (Attributes that do not refer
     to other entities are not shown unless they are part of
     a primary key.)
     This diagram is more or less incomprehensible until you
     actually start looking at the contents of the  catalogs
     and  see  how  they relate to each other.  For now, the
     main things to take away from this diagram are as  follows:
d205 75
a279 57
<ItemizedList Mark="bullet" Spacing="compact">
<ListItem>
<Para>
      In  several of the sections that follow, we will
            present various join queries on the system 
            catalogs  that display information we need to extend
            the system.  Looking at this diagram should make
            some  of  these  join  queries  (which are often
            three- or four-way joins)  more  understandable,
            because  you  will  be  able  to  see  that  the
            attributes used in the queries form foreign keys
            in other classes.
</Para>
</ListItem>
<ListItem>
<Para>  Many  different  features  (classes, attributes,
            functions,  types,  access  methods,  etc.)  are
            tightly  integrated  in  this  schema.  A simple
            create command may modify many  of  these  catalogs.
</Para>
</ListItem>
<ListItem>
<Para>  Types and procedures
            are central to the schema.

<Note>
<Para>
We  use  the words <FirstTerm>procedure</FirstTerm> and <FirstTerm>function</FirstTerm> more or less
interchangably.
</Para>
</Note>

            Nearly  every catalog contains some reference to
            instances in one or both of these classes.   For
            example,  <ProductName>Postgres</ProductName>  frequently  uses type 
            signatures (e.g.,  of  functions  and  operators)  to
            identify unique instances of other catalogs.

</Para>
</ListItem>
<ListItem>
<Para>  There are many attributes and relationships that
            have obvious meanings, but there are many  
            (particularly  those  that  have  to  do with access
            methods) that do not.  The relationships between
            pg_am,   pg_amop,   pg_amproc,  pg_operator  and
            pg_opclass are particularly hard  to  understand
            and  will  be described in depth (in the section
            on interfacing types and operators  to  indices)
            after we have discussed basic extensions.
</para>
</ListItem>
</ItemizedList>

</Para>
</sect1>
</Chapter>
@


1.2
log
@Add id field to chapter and book tags to allow output file names
 to be meaningful.
@
text
@d246 1
d251 1
@


1.1
log
@SGML source for new documentation.
@
text
@d1 1
a1 1
<Chapter>
@
