installation's <literal>SHAREDIR/extension</literal> directory. There

must also be at least one <acronym>SQL</> script file, which follows the

naming pattern

<literal><replaceable>extension</>-<replaceable>version</>.sql</literal>

(for example, <literal>foo-1.0.sql</> for version <literal>1.0</> of

<literal><replaceable>extension</>--<replaceable>version</>.sql</literal>

(for example, <literal>foo--1.0.sql</> for version <literal>1.0</> of

extension <literal>foo</>). By default, the script file(s) are also

placed in the <literal>SHAREDIR/extension</literal> directory; but the

control file can specify a different directory for the script file(s).

<para>

The file format for an extension control file is the same as for the

<filename>postgresql.conf</> file, namely a list of

<replaceable>parameter-name</> <literal>=</> <replaceable>value</>

<replaceable>parameter_name</> <literal>=</> <replaceable>value</>

assignments, one per line. Blank lines and comments introduced by

<literal>#</> are allowed. Be sure to quote any value that is not

a single word or number.

In addition to the primary control file

<literal><replaceable>extension</>.control</literal>,

an extension can have secondary control files named in the style

<literal><replaceable>extension</>-<replaceable>version</>.control</literal>.

<literal><replaceable>extension</>--<replaceable>version</>.control</literal>.

If supplied, these must be located in the script file directory.

Secondary control files follow the same format as the primary control

file. Any parameters set in a secondary control file override the

dynamically from one version to the next, you should provide

<firstterm>update scripts</> that make the necessary changes to go from

one version to the next. Update scripts have names following the pattern

<literal><replaceable>extension</>-<replaceable>oldversion</>-<replaceable>newversion</>.sql</literal>

(for example, <literal>foo-1.0-1.1.sql</> contains the commands to modify

<literal><replaceable>extension</>--<replaceable>oldversion</>--<replaceable>newversion</>.sql</literal>

(for example, <literal>foo--1.0--1.1.sql</> contains the commands to modify

version <literal>1.0</> of extension <literal>foo</> into version

<literal>1.1</>).

</para>

<para>

Given that a suitable update script is available, the command

<command>ALTER EXTENSION...UPDATE</> will update an installed extension

<command>ALTER EXTENSION UPDATE</> will update an installed extension

to the specified new version. The update script is run in the same

environment that <command>CREATE EXTENSION</> provides for installation

scripts: in particular, <varname>search_path</> is set up in the same

class="parameter">old_version</> option, which causes it to not run the

normal installation script for the target version, but instead the update

script named

<literal><replaceable>extension</>-<replaceable>old_version</>-<replaceable>target_version</>.sql</literal>.

<literal><replaceable>extension</>--<replaceable>old_version</>--<replaceable>target_version</>.sql</literal>.

The choice of the dummy version name to use as <replaceable

class="parameter">old_version</> is up to the extension author, though

<literal>unpackaged</> is a common convention. If you have multiple

<para>

<command>ALTER EXTENSION</> is able to execute sequences of update

script files to achieve a requested update. For example, if only

<literal>foo-1.0-1.1.sql</> and <literal>foo-1.1-2.0.sql</> are

<literal>foo--1.0--1.1.sql</> and <literal>foo--1.1--2.0.sql</> are

available, <command>ALTER EXTENSION</> will apply them in sequence if an

update to version <literal>2.0</> is requested when <literal>1.0</> is

currently installed.

of version names: for example, it does not know whether <literal>1.1</>

follows <literal>1.0</>. It just matches up the available version names

and follows the path that requires applying the fewest update scripts.

(A version name can actually be any string that doesn't contain

<literal>--</> or leading or trailing <literal>-</>.)

</para>

<para>

Sometimes it is useful to provide <quote>downgrade</> scripts, for

example <literal>foo-1.1-1.0.sql</> to allow reverting the changes

example <literal>foo--1.1--1.0.sql</> to allow reverting the changes

associated with version <literal>1.1</>. If you do that, be careful

of the possibility that a downgrade script might unexpectedly

get applied because it yields a shorter path. The risky case is where

</para>

<para>

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

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

<programlisting><![CDATA[

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

<programlisting>

EXTENSION = pair

DATA = pair-1.0.sql

DATA = pair--1.0.sql

PG_CONFIG = pg_config

PGXS := $(shell $(PG_CONFIG) --pgxs)

<programlisting>

MODULES = isbn_issn

EXTENSION = isbn_issn

DATA_built = isbn_issn-1.0.sql

DATA = isbn_issn--1.0.sql

DOCS = README.isbn_issn

PG_CONFIG = pg_config

boolcreating_extension= false;

OidCurrentExtensionObject=InvalidOid;

#defineEXT_VERSION_SEP '-'

check_valid_extension_name(constchar*extensionname)

{

intnamelen=strlen(extensionname);

if (namelen==0)

ereport(ERROR,

(errcode(ERRCODE_INVALID_PARAMETER_VALUE),

errmsg("invalid extension name: \"%s\"",extensionname),

errdetail("Extension names must not be empty.")));

if (strstr(extensionname,"--"))

ereport(ERROR,

(errcode(ERRCODE_INVALID_PARAMETER_VALUE),

errmsg("invalid extension name: \"%s\"",extensionname),

errdetail("Extension names must not contain \"--\".")));

if (extensionname[0]=='-'||extensionname[namelen-1]=='-')

ereport(ERROR,

(errcode(ERRCODE_INVALID_PARAMETER_VALUE),

errmsg("invalid extension name: \"%s\"",extensionname),

errdetail("Extension names must not begin or end with \"-\".")));

if (first_dir_separator(extensionname)!=NULL)

ereport(ERROR,

check_valid_version_name(constchar*versionname)

{

if (strchr(versionname,EXT_VERSION_SEP))

intnamelen=strlen(versionname);

if (namelen==0)

ereport(ERROR,

(errcode(ERRCODE_INVALID_PARAMETER_VALUE),

errmsg("invalid extension version name: \"%s\"",versionname),

errdetail("Version names must not be empty.")));

if (strstr(versionname,"--"))

ereport(ERROR,

(errcode(ERRCODE_INVALID_PARAMETER_VALUE),

errmsg("invalid extension version name: \"%s\"",versionname),

errdetail("Version names must not contain \"--\".")));

if (versionname[0]=='-'||versionname[namelen-1]=='-')

ereport(ERROR,

(errcode(ERRCODE_INVALID_PARAMETER_VALUE),

errmsg("invalid extension version name: \"%s\"",versionname),

errdetail("Version names must notcontain the character \"%c\".",

errdetail("Version names must notbegin or end with \"-\".")));

if (first_dir_separator(versionname)!=NULL)

ereport(ERROR,

scriptdir=get_extension_script_directory(control);

result= (char*)palloc(MAXPGPATH);

snprintf(result,MAXPGPATH,"%s/%s%c%s.control",

scriptdir,control->name,EXT_VERSION_SEP,version);

snprintf(result,MAXPGPATH,"%s/%s--%s.control",

scriptdir,control->name,version);

pfree(scriptdir);

result= (char*)palloc(MAXPGPATH);

if (from_version)

snprintf(result,MAXPGPATH,"%s/%s%c%s%c%s.sql",

scriptdir,control->name,EXT_VERSION_SEP,from_version,

EXT_VERSION_SEP,version);

snprintf(result,MAXPGPATH,"%s/%s--%s--%s.sql",

scriptdir,control->name,from_version,version);

snprintf(result,MAXPGPATH,"%s/%s%c%s.sql",

scriptdir,control->name,EXT_VERSION_SEP,version);

snprintf(result,MAXPGPATH,"%s/%s--%s.sql",

scriptdir,control->name,version);

pfree(scriptdir);

if (version)

ereport(ERROR,

(errcode(ERRCODE_SYNTAX_ERROR),

errmsg("parameter \"%s\" cannot be set in aper-version extension control file",

errmsg("parameter \"%s\" cannot be set in asecondary extension control file",

item->name)));

control->directory=pstrdup(item->value);

if (version)

ereport(ERROR,

(errcode(ERRCODE_SYNTAX_ERROR),

errmsg("parameter \"%s\" cannot be set in aper-version extension control file",

errmsg("parameter \"%s\" cannot be set in asecondary extension control file",

item->name)));

control->default_version=pstrdup(item->value);

if (strncmp(de->d_name,control->name,extnamelen)!=0||

de->d_name[extnamelen]!=EXT_VERSION_SEP)

de->d_name[extnamelen]!='-'||

de->d_name[extnamelen+1]!='-')

continue;

vername=pstrdup(de->d_name+extnamelen+1);

vername=pstrdup(de->d_name+extnamelen+2);

*strrchr(vername,'.')='\0';

vername2=strchr(vername,EXT_VERSION_SEP);

vername2=strstr(vername,"--");

if (!vername2)

continue;/* it's not an update script */

*vername2++='\0';

*vername2='\0';/* terminate first version */

vername2+=2;/* and point to second */

evi=get_ext_ver_info(vername,&evi_list);

evi2->distance=newdist;

evi2->previous=evi;

}

elseif (newdist==evi2->distance&&

strcmp(evi->name,evi2->previous->name)<0)

{

evi2->previous=evi;

}

}

}

requiredExtensions);

if (control->comment!=NULL)

CreateComments(extensionOid,ExtensionRelationId,0,control->comment);

extname=pstrdup(de->d_name);

*strrchr(extname,'.')='\0';

if (strstr(extname,"--"))

continue;

control=read_extension_control_file(extname);

memset(values,0,sizeof(values));