<title>Extension Example</title>

    <para>
     Here is a complete example of an <acronym>SQL</acronym>-only
     extension, a two-element composite type that can store any type of value
     in its slots, which are named <quote>k</quote> and <quote>v</quote>.  Non-text
     values are automatically coerced to text for storage.
    </para>

    <para>
     The script file <filename>pair--1.0.sql</filename> looks like this:

<programlisting><![CDATA[
-- complain if script is sourced in psql, rather than via CREATE EXTENSION
\echo Use "CREATE EXTENSION pair" to load this file. \quit

CREATE TYPE pair AS ( k text, v text );

CREATE FUNCTION pair(text, text)
RETURNS pair LANGUAGE SQL AS 'SELECT ROW($1, $2)::@extschema@.pair;';

CREATE OPERATOR ~> (LEFTARG = text, RIGHTARG = text, FUNCTION = pair);

-- "SET search_path" is easy to get right, but qualified names perform better.
CREATE FUNCTION lower(pair)
RETURNS pair LANGUAGE SQL
AS 'SELECT ROW(lower($1.k), lower($1.v))::@extschema@.pair;'
SET search_path = pg_temp;

CREATE FUNCTION pair_concat(pair, pair)
RETURNS pair LANGUAGE SQL
AS 'SELECT ROW($1.k OPERATOR(pg_catalog.||) $2.k,
               $1.v OPERATOR(pg_catalog.||) $2.v)::@extschema@.pair;';
]]>
</programlisting>
    </para>

    <para>
     The control file <filename>pair.control</filename> looks like this:

<programlisting>
# pair extension
comment = 'A key/value pair data type'
default_version = '1.0'
# cannot be relocatable because of use of @extschema@
relocatable = false
</programlisting>
    </para>

    <para>
     While you hardly need a makefile to install these two files into the
     correct directory, you could use a <filename>Makefile</filename> containing this:

<programlisting>
EXTENSION = pair
DATA = pair--1.0.sql

PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)
</programlisting>

     This makefile relies on <acronym>PGXS</acronym>, which is described
     in <xref linkend="extend-pgxs"/>.  The command <literal>make install</literal>
     will install the control and script files into the correct
     directory as reported by <application>pg_config</application>.
    </para>

    <para>
     Once the files are installed, use the
     <command>CREATE EXTENSION</command> command to load the objects into
     any particular database.
    </para>
   </sect2>
  </sect1>

  <sect1 id="extend-pgxs">
   <title>Extension Building Infrastructure</title>

   <indexterm zone="extend-pgxs">
    <primary>pgxs</primary>
   </indexterm>

   <para>
    If you are thinking about distributing your
    <productname>PostgreSQL</productname> extension modules, setting up a
    portable build system for them can be fairly difficult.  Therefore
    the <productname>PostgreSQL</productname> installation provides a build
    infrastructure for extensions, called <acronym>PGXS</acronym>, so
    that simple extension modules can be built simply against an
    already installed server.  <acronym>PGXS</acronym> is mainly intended
    for extensions that include C code, although it can be used for
    pure-SQL extensions too.  Note that <acronym>PGXS</acronym> is not
    intended to be a universal build system framework that can be used
    to build any software interfacing to <productname>PostgreSQL</productname>;
    it simply automates common build rules for simple server extension
    modules.  For more complicated packages, you might need to write your
    own build system.
   </para>

   <para>
    To use the <acronym>PGXS</acronym> infrastructure for your extension,
    you must write a simple makefile.
    In the makefile, you need to set some variables
    and include the global <acronym>PGXS</acronym> makefile.
    Here is an example that builds an extension module named
    <literal>isbn_issn</literal>, consisting of a shared library containing
    some C code, an extension control file, an SQL script, an include file
    (only needed if other modules might need to access the extension functions