2010-09-20 22:08:53 +02:00
<!-- doc/src/sgml/extend.sgml -->
2000-03-31 05:27:42 +02:00
1999-07-22 17:11:05 +02:00
<chapter id="extend">
2003-04-10 03:22:45 +02:00
<title>Extending <acronym>SQL</acronym></title>
1999-07-22 17:11:05 +02:00
2007-08-31 23:33:48 +02:00
<indexterm zone="extend">
<primary>extending SQL</primary>
</indexterm>
2002-11-03 02:31:32 +01:00
1999-07-22 17:11:05 +02:00
<para>
In the sections that follow, we will discuss how you
2010-11-23 21:27:50 +01:00
can extend the <productname>PostgreSQL</productname>
1999-07-22 17:11:05 +02:00
<acronym>SQL</acronym> query language by adding:
<itemizedlist spacing="compact" mark="bullet">
<listitem>
<para>
2017-11-23 15:39:47 +01:00
functions (starting in <xref linkend="xfunc"/>)
1999-07-22 17:11:05 +02:00
</para>
</listitem>
2003-08-10 00:50:22 +02:00
<listitem>
<para>
2017-11-23 15:39:47 +01:00
aggregates (starting in <xref linkend="xaggr"/>)
2003-08-10 00:50:22 +02:00
</para>
</listitem>
1999-07-22 17:11:05 +02:00
<listitem>
<para>
2017-11-23 15:39:47 +01:00
data types (starting in <xref linkend="xtypes"/>)
1999-07-22 17:11:05 +02:00
</para>
</listitem>
<listitem>
<para>
2017-11-23 15:39:47 +01:00
operators (starting in <xref linkend="xoper"/>)
1999-07-22 17:11:05 +02:00
</para>
</listitem>
<listitem>
<para>
2017-11-23 15:39:47 +01:00
operator classes for indexes (starting in <xref linkend="xindex"/>)
1999-07-22 17:11:05 +02:00
</para>
</listitem>
2011-02-08 22:08:41 +01:00
<listitem>
<para>
2017-11-23 15:39:47 +01:00
packages of related objects (starting in <xref linkend="extend-extensions"/>)
2011-02-08 22:08:41 +01:00
</para>
</listitem>
1999-07-22 17:11:05 +02:00
</itemizedlist>
</para>
2000-09-29 22:21:34 +02:00
<sect1 id="extend-how">
1999-07-22 17:11:05 +02:00
<title>How Extensibility Works</title>
<para>
2010-11-23 21:27:50 +01:00
<productname>PostgreSQL</productname> is extensible because its operation is
catalog-driven. If you are familiar with standard
2003-04-10 03:22:45 +02:00
relational database systems, you know that they store information
1999-07-22 17:11:05 +02:00
about databases, tables, columns, etc., in what are
commonly known as system catalogs. (Some systems call
2003-08-10 00:50:22 +02:00
this the data dictionary.) The catalogs appear to the
2001-01-14 00:58:55 +01:00
user as tables like any other, but the <acronym>DBMS</acronym> stores
1999-07-22 17:11:05 +02:00
its internal bookkeeping in them. One key difference
2003-04-10 03:22:45 +02:00
between <productname>PostgreSQL</productname> and standard relational database systems is
2010-11-23 21:27:50 +01:00
that <productname>PostgreSQL</productname> stores much more information in its
2003-04-10 03:22:45 +02:00
catalogs: not only information about tables and columns,
but also information about data types, functions, access
2001-01-14 00:58:55 +01:00
methods, and so on. These tables can be modified by
2010-11-23 21:27:50 +01:00
the user, and since <productname>PostgreSQL</productname> bases its operation
2001-11-21 06:53:41 +01:00
on these tables, this means that <productname>PostgreSQL</productname> can be
1999-07-22 17:11:05 +02:00
extended by users. By comparison, conventional
2010-11-23 21:27:50 +01:00
database systems can only be extended by changing hardcoded
2003-04-10 03:22:45 +02:00
procedures in the source code or by loading modules
2002-01-07 03:29:15 +01:00
specially written by the <acronym>DBMS</acronym> vendor.
1999-07-22 17:11:05 +02:00
</para>
<para>
2003-09-11 23:42:20 +02:00
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.
1999-07-22 17:11:05 +02:00
</para>
</sect1>
2003-08-31 19:32:24 +02:00
<sect1 id="extend-type-system">
2001-11-21 06:53:41 +01:00
<title>The <productname>PostgreSQL</productname> Type System</title>
1999-07-22 17:11:05 +02:00
2003-08-31 19:32:24 +02:00
<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>
2002-11-03 02:31:32 +01:00
</indexterm>
2003-08-31 19:32:24 +02:00
<indexterm zone="extend-type-system">
<primary>data type</primary>
<secondary>composite</secondary>
2002-11-03 02:31:32 +01:00
</indexterm>
Documentation improvements around domain types.
I was a bit surprised to find that domains were almost completely
unmentioned in the main SGML documentation, outside of the reference
pages for CREATE/ALTER/DROP DOMAIN. In particular, noplace was it
mentioned that we don't support domains over composite, making it
hard to document the planned fix for that.
Hence, add a section about domains to chapter 8 (Data Types).
Also, modernize the type system overview in section 37.2; it had never
heard of range types, and insisted on calling arrays base types, which
seems a bit odd from a user's perspective; furthermore it didn't fit well
with the fact that we now support arrays over types other than base types.
It seems appropriate to use the term "container types" to describe all of
arrays, composites, and ranges, so let's do that.
Also a few other minor improvements, notably improve an example query
in rowtypes.sgml by using a LATERAL function instead of an ad-hoc
OFFSET 0 clause.
In part this is mop-up for commit c12d570fa, which missed updating 37.2
to reflect the fact that it added arrays of domains. We could possibly
back-patch this without that claim, but I don't feel a strong need to.
2017-10-24 20:08:40 +02:00
<indexterm zone="extend-type-system">
<primary>container type</primary>
</indexterm>
<indexterm zone="extend-type-system">
<primary>data type</primary>
<secondary>container</secondary>
</indexterm>
1999-07-22 17:11:05 +02:00
<para>
Documentation improvements around domain types.
I was a bit surprised to find that domains were almost completely
unmentioned in the main SGML documentation, outside of the reference
pages for CREATE/ALTER/DROP DOMAIN. In particular, noplace was it
mentioned that we don't support domains over composite, making it
hard to document the planned fix for that.
Hence, add a section about domains to chapter 8 (Data Types).
Also, modernize the type system overview in section 37.2; it had never
heard of range types, and insisted on calling arrays base types, which
seems a bit odd from a user's perspective; furthermore it didn't fit well
with the fact that we now support arrays over types other than base types.
It seems appropriate to use the term "container types" to describe all of
arrays, composites, and ranges, so let's do that.
Also a few other minor improvements, notably improve an example query
in rowtypes.sgml by using a LATERAL function instead of an ad-hoc
OFFSET 0 clause.
In part this is mop-up for commit c12d570fa, which missed updating 37.2
to reflect the fact that it added arrays of domains. We could possibly
back-patch this without that claim, but I don't feel a strong need to.
2017-10-24 20:08:40 +02:00
<productname>PostgreSQL</productname> data types can be divided into base
types, container types, domains, and pseudo-types.
2003-08-10 00:50:22 +02:00
</para>
2003-11-12 23:47:47 +01:00
<sect2>
<title>Base Types</title>
<para>
Documentation improvements around domain types.
I was a bit surprised to find that domains were almost completely
unmentioned in the main SGML documentation, outside of the reference
pages for CREATE/ALTER/DROP DOMAIN. In particular, noplace was it
mentioned that we don't support domains over composite, making it
hard to document the planned fix for that.
Hence, add a section about domains to chapter 8 (Data Types).
Also, modernize the type system overview in section 37.2; it had never
heard of range types, and insisted on calling arrays base types, which
seems a bit odd from a user's perspective; furthermore it didn't fit well
with the fact that we now support arrays over types other than base types.
It seems appropriate to use the term "container types" to describe all of
arrays, composites, and ranges, so let's do that.
Also a few other minor improvements, notably improve an example query
in rowtypes.sgml by using a LATERAL function instead of an ad-hoc
OFFSET 0 clause.
In part this is mop-up for commit c12d570fa, which missed updating 37.2
to reflect the fact that it added arrays of domains. We could possibly
back-patch this without that claim, but I don't feel a strong need to.
2017-10-24 20:08:40 +02:00
Base types are those, like <type>integer</type>, that are
2017-10-09 03:44:17 +02:00
implemented below the level of the <acronym>SQL</acronym> language
2003-11-12 23:47:47 +01:00
(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
Documentation improvements around domain types.
I was a bit surprised to find that domains were almost completely
unmentioned in the main SGML documentation, outside of the reference
pages for CREATE/ALTER/DROP DOMAIN. In particular, noplace was it
mentioned that we don't support domains over composite, making it
hard to document the planned fix for that.
Hence, add a section about domains to chapter 8 (Data Types).
Also, modernize the type system overview in section 37.2; it had never
heard of range types, and insisted on calling arrays base types, which
seems a bit odd from a user's perspective; furthermore it didn't fit well
with the fact that we now support arrays over types other than base types.
It seems appropriate to use the term "container types" to describe all of
arrays, composites, and ranges, so let's do that.
Also a few other minor improvements, notably improve an example query
in rowtypes.sgml by using a LATERAL function instead of an ad-hoc
OFFSET 0 clause.
In part this is mop-up for commit c12d570fa, which missed updating 37.2
to reflect the fact that it added arrays of domains. We could possibly
back-patch this without that claim, but I don't feel a strong need to.
2017-10-24 20:08:40 +02:00
them.
2017-11-23 15:39:47 +01:00
The built-in base types are described in <xref linkend="datatype"/>.
Documentation improvements around domain types.
I was a bit surprised to find that domains were almost completely
unmentioned in the main SGML documentation, outside of the reference
pages for CREATE/ALTER/DROP DOMAIN. In particular, noplace was it
mentioned that we don't support domains over composite, making it
hard to document the planned fix for that.
Hence, add a section about domains to chapter 8 (Data Types).
Also, modernize the type system overview in section 37.2; it had never
heard of range types, and insisted on calling arrays base types, which
seems a bit odd from a user's perspective; furthermore it didn't fit well
with the fact that we now support arrays over types other than base types.
It seems appropriate to use the term "container types" to describe all of
arrays, composites, and ranges, so let's do that.
Also a few other minor improvements, notably improve an example query
in rowtypes.sgml by using a LATERAL function instead of an ad-hoc
OFFSET 0 clause.
In part this is mop-up for commit c12d570fa, which missed updating 37.2
to reflect the fact that it added arrays of domains. We could possibly
back-patch this without that claim, but I don't feel a strong need to.
2017-10-24 20:08:40 +02:00
</para>
<para>
Enumerated (enum) types can be considered as a subcategory of base
types. The main difference is that they can be created using
just <acronym>SQL</acronym> commands, without any low-level programming.
2017-11-23 15:39:47 +01:00
Refer to <xref linkend="datatype-enum"/> for more information.
2003-11-12 23:47:47 +01:00
</para>
</sect2>
<sect2>
Documentation improvements around domain types.
I was a bit surprised to find that domains were almost completely
unmentioned in the main SGML documentation, outside of the reference
pages for CREATE/ALTER/DROP DOMAIN. In particular, noplace was it
mentioned that we don't support domains over composite, making it
hard to document the planned fix for that.
Hence, add a section about domains to chapter 8 (Data Types).
Also, modernize the type system overview in section 37.2; it had never
heard of range types, and insisted on calling arrays base types, which
seems a bit odd from a user's perspective; furthermore it didn't fit well
with the fact that we now support arrays over types other than base types.
It seems appropriate to use the term "container types" to describe all of
arrays, composites, and ranges, so let's do that.
Also a few other minor improvements, notably improve an example query
in rowtypes.sgml by using a LATERAL function instead of an ad-hoc
OFFSET 0 clause.
In part this is mop-up for commit c12d570fa, which missed updating 37.2
to reflect the fact that it added arrays of domains. We could possibly
back-patch this without that claim, but I don't feel a strong need to.
2017-10-24 20:08:40 +02:00
<title>Container Types</title>
<para>
<productname>PostgreSQL</productname> has three kinds
of <quote>container</quote> types, which are types that contain multiple
values of other types. These are arrays, composites, and ranges.
</para>
<para>
Arrays can hold multiple values that are all of the same type. An array
type is automatically created for each base type, composite type, range
type, and domain type. But there are no arrays of arrays. So far as
the type system is concerned, multi-dimensional arrays are the same as
2017-11-23 15:39:47 +01:00
one-dimensional arrays. Refer to <xref linkend="arrays"/> for more
Documentation improvements around domain types.
I was a bit surprised to find that domains were almost completely
unmentioned in the main SGML documentation, outside of the reference
pages for CREATE/ALTER/DROP DOMAIN. In particular, noplace was it
mentioned that we don't support domains over composite, making it
hard to document the planned fix for that.
Hence, add a section about domains to chapter 8 (Data Types).
Also, modernize the type system overview in section 37.2; it had never
heard of range types, and insisted on calling arrays base types, which
seems a bit odd from a user's perspective; furthermore it didn't fit well
with the fact that we now support arrays over types other than base types.
It seems appropriate to use the term "container types" to describe all of
arrays, composites, and ranges, so let's do that.
Also a few other minor improvements, notably improve an example query
in rowtypes.sgml by using a LATERAL function instead of an ad-hoc
OFFSET 0 clause.
In part this is mop-up for commit c12d570fa, which missed updating 37.2
to reflect the fact that it added arrays of domains. We could possibly
back-patch this without that claim, but I don't feel a strong need to.
2017-10-24 20:08:40 +02:00
information.
</para>
2003-11-12 23:47:47 +01:00
<para>
Composite types, or row types, are created whenever the user
2005-10-15 03:47:12 +02:00
creates a table. It is also possible to use <xref
2017-11-23 15:39:47 +01:00
linkend="sql-createtype"/> to
2017-10-09 03:44:17 +02:00
define a <quote>stand-alone</quote> composite type with no associated
2005-10-15 03:47:12 +02:00
table. A composite type is simply a list of types with
associated field names. A value of a composite type is a row or
2017-11-23 15:39:47 +01:00
record of field values. Refer to <xref linkend="rowtypes"/>
Documentation improvements around domain types.
I was a bit surprised to find that domains were almost completely
unmentioned in the main SGML documentation, outside of the reference
pages for CREATE/ALTER/DROP DOMAIN. In particular, noplace was it
mentioned that we don't support domains over composite, making it
hard to document the planned fix for that.
Hence, add a section about domains to chapter 8 (Data Types).
Also, modernize the type system overview in section 37.2; it had never
heard of range types, and insisted on calling arrays base types, which
seems a bit odd from a user's perspective; furthermore it didn't fit well
with the fact that we now support arrays over types other than base types.
It seems appropriate to use the term "container types" to describe all of
arrays, composites, and ranges, so let's do that.
Also a few other minor improvements, notably improve an example query
in rowtypes.sgml by using a LATERAL function instead of an ad-hoc
OFFSET 0 clause.
In part this is mop-up for commit c12d570fa, which missed updating 37.2
to reflect the fact that it added arrays of domains. We could possibly
back-patch this without that claim, but I don't feel a strong need to.
2017-10-24 20:08:40 +02:00
for more information.
</para>
<para>
A range type can hold two values of the same type, which are the lower
and upper bounds of the range. Range types are user-created, although
2017-11-23 15:39:47 +01:00
a few built-in ones exist. Refer to <xref linkend="rangetypes"/>
Documentation improvements around domain types.
I was a bit surprised to find that domains were almost completely
unmentioned in the main SGML documentation, outside of the reference
pages for CREATE/ALTER/DROP DOMAIN. In particular, noplace was it
mentioned that we don't support domains over composite, making it
hard to document the planned fix for that.
Hence, add a section about domains to chapter 8 (Data Types).
Also, modernize the type system overview in section 37.2; it had never
heard of range types, and insisted on calling arrays base types, which
seems a bit odd from a user's perspective; furthermore it didn't fit well
with the fact that we now support arrays over types other than base types.
It seems appropriate to use the term "container types" to describe all of
arrays, composites, and ranges, so let's do that.
Also a few other minor improvements, notably improve an example query
in rowtypes.sgml by using a LATERAL function instead of an ad-hoc
OFFSET 0 clause.
In part this is mop-up for commit c12d570fa, which missed updating 37.2
to reflect the fact that it added arrays of domains. We could possibly
back-patch this without that claim, but I don't feel a strong need to.
2017-10-24 20:08:40 +02:00
for more information.
2003-11-12 23:47:47 +01:00
</para>
</sect2>
2013-05-08 03:23:21 +02:00
<sect2 id="extend-type-system-domains">
2003-11-12 23:47:47 +01:00
<title>Domains</title>
<para>
Documentation improvements around domain types.
I was a bit surprised to find that domains were almost completely
unmentioned in the main SGML documentation, outside of the reference
pages for CREATE/ALTER/DROP DOMAIN. In particular, noplace was it
mentioned that we don't support domains over composite, making it
hard to document the planned fix for that.
Hence, add a section about domains to chapter 8 (Data Types).
Also, modernize the type system overview in section 37.2; it had never
heard of range types, and insisted on calling arrays base types, which
seems a bit odd from a user's perspective; furthermore it didn't fit well
with the fact that we now support arrays over types other than base types.
It seems appropriate to use the term "container types" to describe all of
arrays, composites, and ranges, so let's do that.
Also a few other minor improvements, notably improve an example query
in rowtypes.sgml by using a LATERAL function instead of an ad-hoc
OFFSET 0 clause.
In part this is mop-up for commit c12d570fa, which missed updating 37.2
to reflect the fact that it added arrays of domains. We could possibly
back-patch this without that claim, but I don't feel a strong need to.
2017-10-24 20:08:40 +02:00
A domain is based on a particular underlying type and for many purposes
is interchangeable with its underlying type. However, a domain can have
constraints that restrict its valid values to a subset of what the
underlying type would allow. Domains are created using
2017-11-23 15:39:47 +01:00
the <acronym>SQL</acronym> command <xref linkend="sql-createdomain"/>.
Refer to <xref linkend="domains"/> for more information.
2003-11-12 23:47:47 +01:00
</para>
</sect2>
<sect2>
<title>Pseudo-Types</title>
<para>
2017-10-09 03:44:17 +02:00
There are a few <quote>pseudo-types</quote> for special purposes.
Documentation improvements around domain types.
I was a bit surprised to find that domains were almost completely
unmentioned in the main SGML documentation, outside of the reference
pages for CREATE/ALTER/DROP DOMAIN. In particular, noplace was it
mentioned that we don't support domains over composite, making it
hard to document the planned fix for that.
Hence, add a section about domains to chapter 8 (Data Types).
Also, modernize the type system overview in section 37.2; it had never
heard of range types, and insisted on calling arrays base types, which
seems a bit odd from a user's perspective; furthermore it didn't fit well
with the fact that we now support arrays over types other than base types.
It seems appropriate to use the term "container types" to describe all of
arrays, composites, and ranges, so let's do that.
Also a few other minor improvements, notably improve an example query
in rowtypes.sgml by using a LATERAL function instead of an ad-hoc
OFFSET 0 clause.
In part this is mop-up for commit c12d570fa, which missed updating 37.2
to reflect the fact that it added arrays of domains. We could possibly
back-patch this without that claim, but I don't feel a strong need to.
2017-10-24 20:08:40 +02:00
Pseudo-types cannot appear as columns of tables or components of
container types, but they can be used to declare the argument and
2003-11-12 23:47:47 +01:00
result types of functions. This provides a mechanism within the
type system to identify special classes of functions. <xref
2017-11-23 15:39:47 +01:00
linkend="datatype-pseudotypes-table"/> lists the existing
2003-11-12 23:47:47 +01:00
pseudo-types.
</para>
</sect2>
2003-08-10 00:50:22 +02:00
2003-08-31 19:32:24 +02:00
<sect2 id="extend-types-polymorphic">
2003-11-12 23:47:47 +01:00
<title>Polymorphic Types</title>
2003-08-10 00:50:22 +02:00
2003-08-31 19:32:24 +02:00
<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">
Documentation improvements around domain types.
I was a bit surprised to find that domains were almost completely
unmentioned in the main SGML documentation, outside of the reference
pages for CREATE/ALTER/DROP DOMAIN. In particular, noplace was it
mentioned that we don't support domains over composite, making it
hard to document the planned fix for that.
Hence, add a section about domains to chapter 8 (Data Types).
Also, modernize the type system overview in section 37.2; it had never
heard of range types, and insisted on calling arrays base types, which
seems a bit odd from a user's perspective; furthermore it didn't fit well
with the fact that we now support arrays over types other than base types.
It seems appropriate to use the term "container types" to describe all of
arrays, composites, and ranges, so let's do that.
Also a few other minor improvements, notably improve an example query
in rowtypes.sgml by using a LATERAL function instead of an ad-hoc
OFFSET 0 clause.
In part this is mop-up for commit c12d570fa, which missed updating 37.2
to reflect the fact that it added arrays of domains. We could possibly
back-patch this without that claim, but I don't feel a strong need to.
2017-10-24 20:08:40 +02:00
<primary>data type</primary>
2003-08-31 19:32:24 +02:00
<secondary>polymorphic</secondary>
2003-08-10 00:50:22 +02:00
</indexterm>
2003-08-31 19:32:24 +02:00
<indexterm zone="extend-types-polymorphic">
<primary>function</primary>
<secondary>polymorphic</secondary>
2003-08-10 00:50:22 +02:00
</indexterm>
<para>
2017-10-09 03:44:17 +02:00
Five pseudo-types of special interest are <type>anyelement</type>,
<type>anyarray</type>, <type>anynonarray</type>, <type>anyenum</type>,
and <type>anyrange</type>,
which are collectively called <firstterm>polymorphic types</firstterm>.
2011-11-19 00:23:55 +01:00
Any function declared using these types is said to be
2017-10-09 03:44:17 +02:00
a <firstterm>polymorphic function</firstterm>. A polymorphic function can
2011-11-19 00:23:55 +01:00
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.
2003-08-10 00:50:22 +02:00
</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
2010-11-23 21:27:50 +01:00
<emphasis>same</emphasis> actual type. Each
2003-08-10 00:50:22 +02:00
position declared as <type>anyarray</type> can have any array data type,
2011-11-19 00:23:55 +01:00
but similarly they must all be the same type. And similarly,
positions declared as <type>anyrange</type> must all be the same range
type. Furthermore, if there are
2003-08-10 00:50:22 +02:00
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.
2011-11-03 12:16:28 +01:00
Similarly, if there are positions declared <type>anyrange</type>
2011-11-19 00:23:55 +01:00
and others declared <type>anyelement</type>, the actual range type in
the <type>anyrange</type> positions must be a range whose subtype is
2011-11-03 12:16:28 +01:00
the same type appearing in the <type>anyelement</type> positions.
2017-10-09 03:44:17 +02:00
<type>anynonarray</type> is treated exactly the same as <type>anyelement</type>,
2007-06-07 01:00:50 +02:00
but adds the additional constraint that the actual type must not be
an array type.
2017-10-09 03:44:17 +02:00
<type>anyenum</type> is treated exactly the same as <type>anyelement</type>,
2007-04-02 05:49:42 +02:00
but adds the additional constraint that the actual type must
be an enum type.
2003-08-10 00:50:22 +02:00
</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
2017-10-09 03:44:17 +02:00
<literal>equal(anyelement, anyelement)</literal> will take any two input values,
2003-08-10 00:50:22 +02:00
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)
2017-10-09 03:44:17 +02:00
returns anyelement</literal>. This declaration constrains the actual first
2003-08-10 00:50:22 +02:00
argument to be an array type, and allows the parser to infer the correct
2007-04-02 05:49:42 +02:00
result type from the actual first argument's type. Another example
2017-10-09 03:44:17 +02:00
is that a function declared as <literal>f(anyarray) returns anyenum</literal>
2007-04-02 05:49:42 +02:00
will only accept arrays of enum types.
2003-08-10 00:50:22 +02:00
</para>
2007-06-07 01:00:50 +02:00
<para>
2017-10-09 03:44:17 +02:00
Note that <type>anynonarray</type> and <type>anyenum</type> do not represent
2007-06-07 01:00:50 +02:00
separate type variables; they are the same type as
<type>anyelement</type>, just with an additional constraint. For
2017-10-09 03:44:17 +02:00
example, declaring a function as <literal>f(anyelement, anyenum)</literal>
is equivalent to declaring it as <literal>f(anyenum, anyenum)</literal>:
2007-06-07 01:00:50 +02:00
both actual arguments have to be the same enum type.
</para>
2008-07-16 03:30:23 +02:00
<para>
A variadic function (one taking a variable number of arguments, as in
2017-11-23 15:39:47 +01:00
<xref linkend="xfunc-sql-variadic-functions"/>) can be
2008-07-16 03:30:23 +02:00
polymorphic: this is accomplished by declaring its last parameter as
2017-10-09 03:44:17 +02:00
<literal>VARIADIC</literal> <type>anyarray</type>. For purposes of argument
2008-07-16 03:30:23 +02:00
matching and determining the actual result type, such a function behaves
the same as if you had written the appropriate number of
2017-10-09 03:44:17 +02:00
<type>anynonarray</type> parameters.
2008-07-16 03:30:23 +02:00
</para>
2003-08-10 00:50:22 +02:00
</sect2>
1999-07-22 17:11:05 +02:00
</sect1>
2003-04-10 03:22:45 +02:00
&xfunc;
2003-08-10 00:50:22 +02:00
&xaggr;
2003-04-10 03:22:45 +02:00
&xtypes;
&xoper;
2003-04-13 11:57:35 +02:00
&xindex;
1999-07-22 17:11:05 +02:00
2010-06-01 04:31:36 +02:00
2011-02-08 22:08:41 +01:00
<sect1 id="extend-extensions">
<title>Packaging Related Objects into an Extension</title>
<indexterm zone="extend-extensions">
<primary>extension</primary>
2010-06-01 04:31:36 +02:00
</indexterm>
<para>
2017-10-09 03:44:17 +02:00
A useful extension to <productname>PostgreSQL</productname> typically includes
2011-05-19 00:14:45 +02:00
multiple SQL objects; for example, a new data type will require new
2011-02-08 22:08:41 +01:00
functions, new operators, and probably new index operator classes.
It is helpful to collect all these objects into a single package
2017-10-09 03:44:17 +02:00
to simplify database management. <productname>PostgreSQL</productname> calls
such a package an <firstterm>extension</firstterm>. To define an extension,
you need at least a <firstterm>script file</firstterm> that contains the
<acronym>SQL</acronym> commands to create the extension's objects, and a
<firstterm>control file</firstterm> that specifies a few basic properties
2011-02-08 22:08:41 +01:00
of the extension itself. If the extension includes C code, there
will typically also be a shared library file into which the C code
has been built. Once you have these files, a simple
2017-11-23 15:39:47 +01:00
<xref linkend="sql-createextension"/> command loads the objects into
2011-02-08 22:08:41 +01:00
your database.
</para>
<para>
2011-02-12 03:25:20 +01:00
The main advantage of using an extension, rather than just running the
2017-10-09 03:44:17 +02:00
<acronym>SQL</acronym> script to load a bunch of <quote>loose</quote> objects
into your database, is that <productname>PostgreSQL</productname> will then
2011-02-08 22:08:41 +01:00
understand that the objects of the extension go together. You can
2017-11-23 15:39:47 +01:00
drop all the objects with a single <xref linkend="sql-dropextension"/>
2017-10-09 03:44:17 +02:00
command (no need to maintain a separate <quote>uninstall</quote> script).
Even more useful, <application>pg_dump</application> knows that it should not
2011-02-08 22:08:41 +01:00
dump the individual member objects of the extension — it will
2017-10-09 03:44:17 +02:00
just include a <command>CREATE EXTENSION</command> command in dumps, instead.
2011-02-08 22:08:41 +01:00
This vastly simplifies migration to a new version of the extension
that might contain more or different objects than the old version.
Note however that you must have the extension's control, script, and
other files available when loading such a dump into a new database.
</para>
<para>
2017-10-09 03:44:17 +02:00
<productname>PostgreSQL</productname> will not let you drop an individual object
2011-02-08 22:08:41 +01:00
contained in an extension, except by dropping the whole extension.
Also, while you can change the definition of an extension member object
(for example, via <command>CREATE OR REPLACE FUNCTION</command> for a
function), bear in mind that the modified definition will not be dumped
2017-10-09 03:44:17 +02:00
by <application>pg_dump</application>. Such a change is usually only sensible if
2011-02-08 22:08:41 +01:00
you concurrently make the same change in the extension's script file.
(But there are special provisions for tables containing configuration
2017-11-23 15:39:47 +01:00
data; see <xref linkend="extend-extensions-config-tables"/>.)
2016-09-07 19:36:08 +02:00
In production situations, it's generally better to create an extension
update script to perform changes to extension member objects.
2011-02-08 22:08:41 +01:00
</para>
2016-04-07 03:45:32 +02:00
<para>
2016-09-07 19:36:08 +02:00
The extension script may set privileges on objects that are part of the
2016-04-07 03:45:32 +02:00
extension via <command>GRANT</command> and <command>REVOKE</command>
statements. The final set of privileges for each object (if any are set)
will be stored in the
<link linkend="catalog-pg-init-privs"><structname>pg_init_privs</structname></link>
2017-10-09 03:44:17 +02:00
system catalog. When <application>pg_dump</application> is used, the
<command>CREATE EXTENSION</command> command will be included in the dump, followed
2016-04-07 03:45:32 +02:00
by the set of <command>GRANT</command> and <command>REVOKE</command>
statements necessary to set the privileges on the objects to what they were
at the time the dump was taken.
</para>
<para>
2017-10-09 03:44:17 +02:00
<productname>PostgreSQL</productname> does not currently support extension scripts
2016-04-07 03:45:32 +02:00
issuing <command>CREATE POLICY</command> or <command>SECURITY LABEL</command>
statements. These are expected to be set after the extension has been
created. All RLS policies and security labels on extension objects will be
2017-10-09 03:44:17 +02:00
included in dumps created by <application>pg_dump</application>.
2016-04-07 03:45:32 +02:00
</para>
2011-02-12 03:25:20 +01:00
<para>
The extension mechanism also has provisions for packaging modification
scripts that adjust the definitions of the SQL objects contained in an
extension. For example, if version 1.1 of an extension adds one function
and changes the body of another function compared to 1.0, the extension
2017-10-09 03:44:17 +02:00
author can provide an <firstterm>update script</firstterm> that makes just those
two changes. The <command>ALTER EXTENSION UPDATE</command> command can then
2011-02-12 03:25:20 +01:00
be used to apply these changes and track which version of the extension
is actually installed in a given database.
</para>
2011-02-09 17:55:32 +01:00
<para>
The kinds of SQL objects that can be members of an extension are shown in
2017-11-23 15:39:47 +01:00
the description of <xref linkend="sql-alterextension"/>. Notably, objects
2011-02-09 17:55:32 +01:00
that are database-cluster-wide, such as databases, roles, and tablespaces,
cannot be extension members since an extension is only known within one
database. (Although an extension script is not prohibited from creating
such objects, if it does so they will not be tracked as part of the
extension.) Also notice that while a table can be a member of an
extension, its subsidiary objects such as indexes are not directly
considered members of the extension.
2013-04-05 04:37:25 +02:00
Another important point is that schemas can belong to extensions, but not
vice versa: an extension as such has an unqualified name and does not
2017-10-09 03:44:17 +02:00
exist <quote>within</quote> any schema. The extension's member objects,
2013-04-05 04:37:25 +02:00
however, will belong to schemas whenever appropriate for their object
types. It may or may not be appropriate for an extension to own the
schema(s) its member objects are within.
2011-02-09 17:55:32 +01:00
</para>
Delete deleteWhatDependsOn() in favor of more performDeletion() flag bits.
deleteWhatDependsOn() had grown an uncomfortably large number of
assumptions about what it's used for. There are actually only two minor
differences between what it does and what a regular performDeletion() call
can do, so let's invent additional bits in performDeletion's existing flags
argument that specify those behaviors, and get rid of deleteWhatDependsOn()
as such. (We'd probably have done it this way from the start, except that
performDeletion didn't originally have a flags argument, IIRC.)
Also, add a SKIP_EXTENSIONS flag bit that prevents ever recursing to an
extension, and use that when dropping temporary objects at session end.
This provides a more general solution to the problem addressed in a hacky
way in commit 08dd23cec: if an extension script creates temp objects and
forgets to remove them again, the whole extension went away when its
contained temp objects were deleted. The previous solution only covered
temp relations, but this solves it for all object types.
These changes require minor additions in dependency.c to pass the flags
to subroutines that previously didn't get them, but it's still a net
savings of code, and it seems cleaner than before.
Having done this, revert the special-case code added in 08dd23cec that
prevented addition of pg_depend records for temp table extension
membership, because that caused its own oddities: dropping an extension
that had created such a table didn't automatically remove the table,
leading to a failure if the table had another dependency on the extension
(such as use of an extension data type), or to a duplicate-name failure if
you then tried to recreate the extension. But we keep the part that
prevents the pg_temp_nnn schema from becoming an extension member; we never
want that to happen. Add a regression test case covering these behaviors.
Although this fixes some arguable bugs, we've heard few field complaints,
and any such problems are easily worked around by explicitly dropping temp
objects at the end of extension scripts (which seems like good practice
anyway). So I won't risk a back-patch.
Discussion: https://postgr.es/m/e51f4311-f483-4dd0-1ccc-abec3c405110@BlueTreble.com
2016-12-02 20:57:35 +01:00
<para>
If an extension's script creates any temporary objects (such as temp
tables), those objects are treated as extension members for the
remainder of the current session, but are automatically dropped at
session end, as any temporary object would be. This is an exception
to the rule that extension member objects cannot be dropped without
dropping the whole extension.
</para>
Document security implications of search_path and the public schema.
The ability to create like-named objects in different schemas opens up
the potential for users to change the behavior of other users' queries,
maliciously or accidentally. When you connect to a PostgreSQL server,
you should remove from your search_path any schema for which a user
other than yourself or superusers holds the CREATE privilege. If you do
not, other users holding CREATE privilege can redefine the behavior of
your commands, causing them to perform arbitrary SQL statements under
your identity. "SET search_path = ..." and "SELECT
pg_catalog.set_config(...)" are not vulnerable to such hijacking, so one
can use either as the first command of a session. As special
exceptions, the following client applications behave as documented
regardless of search_path settings and schema privileges: clusterdb
createdb createlang createuser dropdb droplang dropuser ecpg (not
programs it generates) initdb oid2name pg_archivecleanup pg_basebackup
pg_config pg_controldata pg_ctl pg_dump pg_dumpall pg_isready
pg_receivewal pg_recvlogical pg_resetwal pg_restore pg_rewind pg_standby
pg_test_fsync pg_test_timing pg_upgrade pg_waldump reindexdb vacuumdb
vacuumlo. Not included are core client programs that run user-specified
SQL commands, namely psql and pgbench. PostgreSQL encourages non-core
client applications to do likewise.
Document this in the context of libpq connections, psql connections,
dblink connections, ECPG connections, extension packaging, and schema
usage patterns. The principal defense for applications is "SELECT
pg_catalog.set_config('search_path', '', false)", and the principal
defense for databases is "REVOKE CREATE ON SCHEMA public FROM PUBLIC".
Either one is sufficient to prevent attack. After a REVOKE, consider
auditing the public schema for objects named like pg_catalog objects.
Authors of SECURITY DEFINER functions use some of the same defenses, and
the CREATE FUNCTION reference page already covered them thoroughly.
This is a good opportunity to audit SECURITY DEFINER functions for
robust security practice.
Back-patch to 9.3 (all supported versions).
Reviewed by Michael Paquier and Jonathan S. Katz. Reported by Arseniy
Sharoglazov.
Security: CVE-2018-1058
2018-02-26 16:39:44 +01:00
<sect2 id="extend-extensions-style">
<title>Defining Extension Objects</title>
<!-- XXX It's not enough to use qualified names, because one might write a
qualified name to an object that itself uses unqualified names. Many
information_schema functions have that defect, for example. However,
that's a defect in the referenced object, and relatively few queries
will be affected. Also, we direct applications to secure search_path
when connecting to an untrusted database; if applications do that,
they are immune to known attacks even if some extension refers to a
defective object. Therefore, guide extension authors as though core
PostgreSQL contained no such defect. -->
<para>
Widely-distributed extensions should assume little about the database
they occupy. In particular, unless you issued <literal>SET search_path =
pg_temp</literal>, assume each unqualified name could resolve to an
object that a malicious user has defined. Beware of constructs that
depend on <varname>search_path</varname> implicitly: <token>IN</token>
and <literal>CASE <replaceable>expression</replaceable> WHEN</literal>
always select an operator using the search path. In their place, use
<literal>OPERATOR(<replaceable>schema</replaceable>.=) ANY</literal>
and <literal>CASE WHEN <replaceable>expression</replaceable></literal>.
</para>
</sect2>
2011-06-10 00:44:05 +02:00
<sect2>
2011-02-08 22:08:41 +01:00
<title>Extension Files</title>
<indexterm>
<primary>control file</primary>
</indexterm>
<para>
2017-11-23 15:39:47 +01:00
The <xref linkend="sql-createextension"/> command relies on a control
2011-02-08 22:08:41 +01:00
file for each extension, which must be named the same as the extension
2017-10-09 03:44:17 +02:00
with a suffix of <literal>.control</literal>, and must be placed in the
2011-02-12 04:53:43 +01:00
installation's <literal>SHAREDIR/extension</literal> directory. There
2017-10-09 03:44:17 +02:00
must also be at least one <acronym>SQL</acronym> script file, which follows the
2011-02-12 03:25:20 +01:00
naming pattern
2017-10-09 03:44:17 +02:00
<literal><replaceable>extension</replaceable>--<replaceable>version</replaceable>.sql</literal>
(for example, <literal>foo--1.0.sql</literal> for version <literal>1.0</literal> of
extension <literal>foo</literal>). By default, the script file(s) are also
2011-02-12 04:53:43 +01:00
placed in the <literal>SHAREDIR/extension</literal> directory; but the
2011-02-12 03:25:20 +01:00
control file can specify a different directory for the script file(s).
2011-02-08 22:08:41 +01:00
</para>
<para>
The file format for an extension control file is the same as for the
2017-10-09 03:44:17 +02:00
<filename>postgresql.conf</filename> file, namely a list of
<replaceable>parameter_name</replaceable> <literal>=</literal> <replaceable>value</replaceable>
2011-02-08 22:08:41 +01:00
assignments, one per line. Blank lines and comments introduced by
2017-10-09 03:44:17 +02:00
<literal>#</literal> are allowed. Be sure to quote any value that is not
2011-02-08 22:08:41 +01:00
a single word or number.
</para>
<para>
A control file can set the following parameters:
</para>
<variablelist>
<varlistentry>
2011-02-12 03:25:20 +01:00
<term><varname>directory</varname> (<type>string</type>)</term>
2011-02-08 22:08:41 +01:00
<listitem>
<para>
2017-10-09 03:44:17 +02:00
The directory containing the extension's <acronym>SQL</acronym> script
2011-02-12 03:25:20 +01:00
file(s). Unless an absolute path is given, the name is relative to
2011-02-12 04:53:43 +01:00
the installation's <literal>SHAREDIR</literal> directory. The
default behavior is equivalent to specifying
2017-10-09 03:44:17 +02:00
<literal>directory = 'extension'</literal>.
2011-02-08 22:08:41 +01:00
</para>
</listitem>
</varlistentry>
<varlistentry>
2011-02-12 03:25:20 +01:00
<term><varname>default_version</varname> (<type>string</type>)</term>
2011-02-08 22:08:41 +01:00
<listitem>
<para>
2011-02-12 03:25:20 +01:00
The default version of the extension (the one that will be installed
2017-10-09 03:44:17 +02:00
if no version is specified in <command>CREATE EXTENSION</command>). Although
this can be omitted, that will result in <command>CREATE EXTENSION</command>
failing if no <literal>VERSION</literal> option appears, so you generally
2011-02-12 03:25:20 +01:00
don't want to do that.
2011-02-08 22:08:41 +01:00
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>comment</varname> (<type>string</type>)</term>
<listitem>
<para>
2016-09-07 19:36:08 +02:00
A comment (any string) about the extension. The comment is applied
when initially creating an extension, but not during extension updates
(since that might override user-added comments). Alternatively,
the extension's comment can be set by writing
2017-11-23 15:39:47 +01:00
a <xref linkend="sql-comment"/> command in the script file.
2011-02-08 22:08:41 +01:00
</para>
</listitem>
</varlistentry>
<varlistentry>
2011-02-13 19:38:05 +01:00
<term><varname>encoding</varname> (<type>string</type>)</term>
2011-02-08 22:08:41 +01:00
<listitem>
<para>
2011-02-13 19:38:05 +01:00
The character set encoding used by the script file(s). This should
be specified if the script files contain any non-ASCII characters.
Otherwise the files will be assumed to be in the database encoding.
2011-02-08 22:08:41 +01:00
</para>
</listitem>
</varlistentry>
<varlistentry>
2011-02-13 19:38:05 +01:00
<term><varname>module_pathname</varname> (<type>string</type>)</term>
2011-02-08 22:08:41 +01:00
<listitem>
<para>
2011-02-13 19:38:05 +01:00
The value of this parameter will be substituted for each occurrence
2017-10-09 03:44:17 +02:00
of <literal>MODULE_PATHNAME</literal> in the script file(s). If it is not
2011-02-13 19:38:05 +01:00
set, no substitution is made. Typically, this is set to
2017-10-09 03:44:17 +02:00
<literal>$libdir/<replaceable>shared_library_name</replaceable></literal> and
then <literal>MODULE_PATHNAME</literal> is used in <command>CREATE
FUNCTION</command> commands for C-language functions, so that the script
2011-02-13 19:38:05 +01:00
files do not need to hard-wire the name of the shared library.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>requires</varname> (<type>string</type>)</term>
<listitem>
<para>
A list of names of extensions that this extension depends on,
for example <literal>requires = 'foo, bar'</literal>. Those
extensions must be installed before this one can be installed.
2011-02-08 22:08:41 +01:00
</para>
</listitem>
</varlistentry>
2011-03-04 22:08:24 +01:00
<varlistentry>
<term><varname>superuser</varname> (<type>boolean</type>)</term>
<listitem>
<para>
2017-10-09 03:44:17 +02:00
If this parameter is <literal>true</literal> (which is the default),
2011-03-04 22:08:24 +01:00
only superusers can create the extension or update it to a new
2017-10-09 03:44:17 +02:00
version. If it is set to <literal>false</literal>, just the privileges
2011-03-04 22:08:24 +01:00
required to execute the commands in the installation or update script
are required.
</para>
</listitem>
</varlistentry>
2011-02-08 22:08:41 +01:00
<varlistentry>
<term><varname>relocatable</varname> (<type>boolean</type>)</term>
<listitem>
<para>
2017-10-09 03:44:17 +02:00
An extension is <firstterm>relocatable</firstterm> if it is possible to move
2011-02-08 22:08:41 +01:00
its contained objects into a different schema after initial creation
2017-10-09 03:44:17 +02:00
of the extension. The default is <literal>false</literal>, i.e. the
2011-02-08 22:08:41 +01:00
extension is not relocatable.
2017-11-23 15:39:47 +01:00
See <xref linkend="extend-extensions-relocation"/> for more information.
2011-02-08 22:08:41 +01:00
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>schema</varname> (<type>string</type>)</term>
<listitem>
<para>
This parameter can only be set for non-relocatable extensions.
It forces the extension to be loaded into exactly the named schema
2016-09-07 19:36:08 +02:00
and not any other.
The <varname>schema</varname> parameter is consulted only when
initially creating an extension, not during extension updates.
2017-11-23 15:39:47 +01:00
See <xref linkend="extend-extensions-relocation"/> for more information.
2011-02-08 22:08:41 +01:00
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
2011-02-12 03:25:20 +01:00
In addition to the primary control file
2017-10-09 03:44:17 +02:00
<literal><replaceable>extension</replaceable>.control</literal>,
2011-02-12 03:25:20 +01:00
an extension can have secondary control files named in the style
2017-10-09 03:44:17 +02:00
<literal><replaceable>extension</replaceable>--<replaceable>version</replaceable>.control</literal>.
2011-02-12 03:25:20 +01:00
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
primary control file when installing or updating to that version of
2017-10-09 03:44:17 +02:00
the extension. However, the parameters <varname>directory</varname> and
<varname>default_version</varname> cannot be set in a secondary control file.
2011-02-12 03:25:20 +01:00
</para>
<para>
2017-10-09 03:44:17 +02:00
An extension's <acronym>SQL</acronym> script files can contain any SQL commands,
except for transaction control commands (<command>BEGIN</command>,
<command>COMMIT</command>, etc) and commands that cannot be executed inside a
transaction block (such as <command>VACUUM</command>). This is because the
2011-02-12 03:25:20 +01:00
script files are implicitly executed within a transaction block.
2011-02-08 22:08:41 +01:00
</para>
2011-10-12 21:45:03 +02:00
<para>
2017-10-09 03:44:17 +02:00
An extension's <acronym>SQL</acronym> script files can also contain lines
beginning with <literal>\echo</literal>, which will be ignored (treated as
2011-10-12 21:45:03 +02:00
comments) by the extension mechanism. This provision is commonly used
2017-10-09 03:44:17 +02:00
to throw an error if the script file is fed to <application>psql</application>
rather than being loaded via <command>CREATE EXTENSION</command> (see example
2017-11-23 15:39:47 +01:00
script in <xref linkend="extend-extensions-example"/>).
2016-09-07 19:36:08 +02:00
Without that, users might accidentally load the
2017-10-09 03:44:17 +02:00
extension's contents as <quote>loose</quote> objects rather than as an
2011-10-12 21:45:03 +02:00
extension, a state of affairs that's a bit tedious to recover from.
</para>
2011-02-08 22:08:41 +01:00
<para>
2011-02-12 03:25:20 +01:00
While the script files can contain any characters allowed by the specified
encoding, control files should contain only plain ASCII, because there
2017-10-09 03:44:17 +02:00
is no way for <productname>PostgreSQL</productname> to know what encoding a
2011-02-08 22:08:41 +01:00
control file is in. In practice this is only an issue if you want to
use non-ASCII characters in the extension's comment. Recommended
2017-10-09 03:44:17 +02:00
practice in that case is to not use the control file <varname>comment</varname>
parameter, but instead use <command>COMMENT ON EXTENSION</command>
2011-02-12 03:25:20 +01:00
within a script file to set the comment.
2011-02-08 22:08:41 +01:00
</para>
</sect2>
2016-09-07 19:36:08 +02:00
<sect2 id="extend-extensions-relocation">
2011-02-08 22:08:41 +01:00
<title>Extension Relocatability</title>
<para>
Users often wish to load the objects contained in an extension into a
different schema than the extension's author had in mind. There are
three supported levels of relocatability:
</para>
2010-06-01 04:31:36 +02:00
<itemizedlist>
<listitem>
<para>
2011-02-08 22:08:41 +01:00
A fully relocatable extension can be moved into another schema
at any time, even after it's been loaded into a database.
2017-10-09 03:44:17 +02:00
This is done with the <command>ALTER EXTENSION SET SCHEMA</command>
2011-02-08 22:08:41 +01:00
command, which automatically renames all the member objects into
the new schema. Normally, this is only possible if the extension
contains no internal assumptions about what schema any of its
objects are in. Also, the extension's objects must all be in one
schema to begin with (ignoring objects that do not belong to any
schema, such as procedural languages). Mark a fully relocatable
2017-10-09 03:44:17 +02:00
extension by setting <literal>relocatable = true</literal> in its control
2011-02-08 22:08:41 +01:00
file.
2010-06-03 16:41:25 +02:00
</para>
2010-06-01 04:31:36 +02:00
</listitem>
2011-02-08 22:08:41 +01:00
2010-06-01 04:31:36 +02:00
<listitem>
<para>
2011-02-08 22:08:41 +01:00
An extension might be relocatable during installation but not
afterwards. This is typically the case if the extension's script
file needs to reference the target schema explicitly, for example
2017-10-09 03:44:17 +02:00
in setting <literal>search_path</literal> properties for SQL functions.
For such an extension, set <literal>relocatable = false</literal> in its
control file, and use <literal>@extschema@</literal> to refer to the target
2011-02-08 22:08:41 +01:00
schema in the script file. All occurrences of this string will be
replaced by the actual target schema's name before the script is
executed. The user can set the target schema using the
2017-10-09 03:44:17 +02:00
<literal>SCHEMA</literal> option of <command>CREATE EXTENSION</command>.
2010-06-01 04:31:36 +02:00
</para>
</listitem>
2011-02-08 22:08:41 +01:00
2010-06-01 04:31:36 +02:00
<listitem>
<para>
2011-02-08 22:08:41 +01:00
If the extension does not support relocation at all, set
2017-10-09 03:44:17 +02:00
<literal>relocatable = false</literal> in its control file, and also set
<literal>schema</literal> to the name of the intended target schema. This
will prevent use of the <literal>SCHEMA</literal> option of <command>CREATE
EXTENSION</command>, unless it specifies the same schema named in the control
2011-02-08 22:08:41 +01:00
file. This choice is typically necessary if the extension contains
internal assumptions about schema names that can't be replaced by
2017-10-09 03:44:17 +02:00
uses of <literal>@extschema@</literal>. The <literal>@extschema@</literal>
2011-02-08 22:08:41 +01:00
substitution mechanism is available in this case too, although it is
of limited use since the schema name is determined by the control file.
2010-06-01 04:31:36 +02:00
</para>
</listitem>
</itemizedlist>
2011-02-08 22:08:41 +01:00
<para>
In all cases, the script file will be executed with
2017-11-23 15:39:47 +01:00
<xref linkend="guc-search-path"/> initially set to point to the target
2017-10-09 03:44:17 +02:00
schema; that is, <command>CREATE EXTENSION</command> does the equivalent of
2011-02-08 22:08:41 +01:00
this:
<programlisting>
SET LOCAL search_path TO @extschema@;
</programlisting>
This allows the objects created by the script file to go into the target
2017-10-09 03:44:17 +02:00
schema. The script file can change <varname>search_path</varname> if it wishes,
but that is generally undesirable. <varname>search_path</varname> is restored
to its previous setting upon completion of <command>CREATE EXTENSION</command>.
2011-02-08 22:08:41 +01:00
</para>
<para>
2017-10-09 03:44:17 +02:00
The target schema is determined by the <varname>schema</varname> parameter in
the control file if that is given, otherwise by the <literal>SCHEMA</literal>
option of <command>CREATE EXTENSION</command> if that is given, otherwise the
2011-02-08 22:08:41 +01:00
current default object creation schema (the first one in the caller's
2017-10-09 03:44:17 +02:00
<varname>search_path</varname>). When the control file <varname>schema</varname>
2011-02-08 22:08:41 +01:00
parameter is used, the target schema will be created if it doesn't
already exist, but in the other two cases it must already exist.
</para>
<para>
If any prerequisite extensions are listed in <varname>requires</varname>
in the control file, their target schemas are appended to the initial
2017-10-09 03:44:17 +02:00
setting of <varname>search_path</varname>. This allows their objects to be
2011-02-08 22:08:41 +01:00
visible to the new extension's script file.
</para>
<para>
Although a non-relocatable extension can contain objects spread across
multiple schemas, it is usually desirable to place all the objects meant
for external use into a single schema, which is considered the extension's
target schema. Such an arrangement works conveniently with the default
2017-10-09 03:44:17 +02:00
setting of <varname>search_path</varname> during creation of dependent
2011-02-08 22:08:41 +01:00
extensions.
</para>
</sect2>
2016-09-07 19:36:08 +02:00
<sect2 id="extend-extensions-config-tables">
2011-02-08 22:08:41 +01:00
<title>Extension Configuration Tables</title>
<para>
Some extensions include configuration tables, which contain data that
might be added or changed by the user after installation of the
extension. Ordinarily, if a table is part of an extension, neither
the table's definition nor its content will be dumped by
2017-10-09 03:44:17 +02:00
<application>pg_dump</application>. But that behavior is undesirable for a
2011-02-08 22:08:41 +01:00
configuration table; any data changes made by the user need to be
included in dumps, or the extension will behave differently after a dump
and reload.
</para>
2012-12-20 22:30:59 +01:00
<indexterm>
<primary>pg_extension_config_dump</primary>
</indexterm>
2011-02-08 22:08:41 +01:00
<para>
To solve this problem, an extension's script file can mark a table
2016-04-18 05:13:45 +02:00
or a sequence it has created as a configuration relation, which will
2017-10-09 03:44:17 +02:00
cause <application>pg_dump</application> to include the table's or the sequence's
2016-04-18 05:13:45 +02:00
contents (not its definition) in dumps. To do that, call the function
2017-10-09 03:44:17 +02:00
<function>pg_extension_config_dump(regclass, text)</function> after creating the
2016-04-18 05:13:45 +02:00
table or the sequence, for example
2011-02-08 22:08:41 +01:00
<programlisting>
CREATE TABLE my_config (key text, value text);
2016-04-18 05:13:45 +02:00
CREATE SEQUENCE my_config_seq;
2011-02-08 22:08:41 +01:00
SELECT pg_catalog.pg_extension_config_dump('my_config', '');
2016-04-18 05:13:45 +02:00
SELECT pg_catalog.pg_extension_config_dump('my_config_seq', '');
2011-02-08 22:08:41 +01:00
</programlisting>
2016-04-18 05:13:45 +02:00
Any number of tables or sequences can be marked this way. Sequences
2017-10-09 03:44:17 +02:00
associated with <type>serial</type> or <type>bigserial</type> columns can
2016-04-18 05:13:45 +02:00
be marked as well.
2011-02-08 22:08:41 +01:00
</para>
<para>
2017-10-09 03:44:17 +02:00
When the second argument of <function>pg_extension_config_dump</function> is
2011-02-08 22:08:41 +01:00
an empty string, the entire contents of the table are dumped by
2017-10-09 03:44:17 +02:00
<application>pg_dump</application>. This is usually only correct if the table
2011-02-08 22:08:41 +01:00
is initially empty as created by the extension script. If there is
a mixture of initial data and user-provided data in the table,
2017-10-09 03:44:17 +02:00
the second argument of <function>pg_extension_config_dump</function> provides
a <literal>WHERE</literal> condition that selects the data to be dumped.
2011-02-08 22:08:41 +01:00
For example, you might do
<programlisting>
CREATE TABLE my_config (key text, value text, standard_entry boolean);
SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entry');
</programlisting>
2017-10-09 03:44:17 +02:00
and then make sure that <structfield>standard_entry</structfield> is true only
2011-02-08 22:08:41 +01:00
in the rows created by the extension's script.
</para>
2016-04-18 05:13:45 +02:00
<para>
2017-10-09 03:44:17 +02:00
For sequences, the second argument of <function>pg_extension_config_dump</function>
2016-04-18 05:13:45 +02:00
has no effect.
</para>
2011-02-08 22:08:41 +01:00
<para>
More complicated situations, such as initially-provided rows that might
be modified by users, can be handled by creating triggers on the
configuration table to ensure that modified rows are marked correctly.
</para>
2012-12-20 22:30:59 +01:00
<para>
You can alter the filter condition associated with a configuration table
2017-10-09 03:44:17 +02:00
by calling <function>pg_extension_config_dump</function> again. (This would
2012-12-20 22:30:59 +01:00
typically be useful in an extension update script.) The only way to mark
a table as no longer a configuration table is to dissociate it from the
2017-10-09 03:44:17 +02:00
extension with <command>ALTER EXTENSION ... DROP TABLE</command>.
2012-12-20 22:30:59 +01:00
</para>
2015-03-02 20:12:21 +01:00
<para>
Note that foreign key relationships between these tables will dictate the
order in which the tables are dumped out by pg_dump. Specifically, pg_dump
will attempt to dump the referenced-by table before the referencing table.
As the foreign key relationships are set up at CREATE EXTENSION time (prior
to data being loaded into the tables) circular dependencies are not
supported. When circular dependencies exist, the data will still be dumped
out but the dump will not be able to be restored directly and user
intervention will be required.
</para>
2016-09-07 19:36:08 +02:00
2016-04-18 05:13:45 +02:00
<para>
2017-10-09 03:44:17 +02:00
Sequences associated with <type>serial</type> or <type>bigserial</type> columns
2016-04-18 05:13:45 +02:00
need to be directly marked to dump their state. Marking their parent
relation is not enough for this purpose.
</para>
2011-02-08 22:08:41 +01:00
</sect2>
2011-02-12 03:25:20 +01:00
<sect2>
<title>Extension Updates</title>
<para>
One advantage of the extension mechanism is that it provides convenient
ways to manage updates to the SQL commands that define an extension's
objects. This is done by associating a version name or number with
each released version of the extension's installation script.
In addition, if you want users to be able to update their databases
dynamically from one version to the next, you should provide
2017-10-09 03:44:17 +02:00
<firstterm>update scripts</firstterm> that make the necessary changes to go from
2011-02-12 03:25:20 +01:00
one version to the next. Update scripts have names following the pattern
2017-10-09 03:44:17 +02:00
<literal><replaceable>extension</replaceable>--<replaceable>oldversion</replaceable>--<replaceable>newversion</replaceable>.sql</literal>
(for example, <literal>foo--1.0--1.1.sql</literal> contains the commands to modify
version <literal>1.0</literal> of extension <literal>foo</literal> into version
<literal>1.1</literal>).
2011-02-12 03:25:20 +01:00
</para>
<para>
Given that a suitable update script is available, the command
2017-10-09 03:44:17 +02:00
<command>ALTER EXTENSION UPDATE</command> will update an installed extension
2011-02-12 03:25:20 +01:00
to the specified new version. The update script is run in the same
2017-10-09 03:44:17 +02:00
environment that <command>CREATE EXTENSION</command> provides for installation
scripts: in particular, <varname>search_path</varname> is set up in the same
2011-02-12 03:25:20 +01:00
way, and any new objects created by the script are automatically added
Delete deleteWhatDependsOn() in favor of more performDeletion() flag bits.
deleteWhatDependsOn() had grown an uncomfortably large number of
assumptions about what it's used for. There are actually only two minor
differences between what it does and what a regular performDeletion() call
can do, so let's invent additional bits in performDeletion's existing flags
argument that specify those behaviors, and get rid of deleteWhatDependsOn()
as such. (We'd probably have done it this way from the start, except that
performDeletion didn't originally have a flags argument, IIRC.)
Also, add a SKIP_EXTENSIONS flag bit that prevents ever recursing to an
extension, and use that when dropping temporary objects at session end.
This provides a more general solution to the problem addressed in a hacky
way in commit 08dd23cec: if an extension script creates temp objects and
forgets to remove them again, the whole extension went away when its
contained temp objects were deleted. The previous solution only covered
temp relations, but this solves it for all object types.
These changes require minor additions in dependency.c to pass the flags
to subroutines that previously didn't get them, but it's still a net
savings of code, and it seems cleaner than before.
Having done this, revert the special-case code added in 08dd23cec that
prevented addition of pg_depend records for temp table extension
membership, because that caused its own oddities: dropping an extension
that had created such a table didn't automatically remove the table,
leading to a failure if the table had another dependency on the extension
(such as use of an extension data type), or to a duplicate-name failure if
you then tried to recreate the extension. But we keep the part that
prevents the pg_temp_nnn schema from becoming an extension member; we never
want that to happen. Add a regression test case covering these behaviors.
Although this fixes some arguable bugs, we've heard few field complaints,
and any such problems are easily worked around by explicitly dropping temp
objects at the end of extension scripts (which seems like good practice
anyway). So I won't risk a back-patch.
Discussion: https://postgr.es/m/e51f4311-f483-4dd0-1ccc-abec3c405110@BlueTreble.com
2016-12-02 20:57:35 +01:00
to the extension. Also, if the script chooses to drop extension member
objects, they are automatically dissociated from the extension.
2011-02-12 03:25:20 +01:00
</para>
2011-02-12 22:40:41 +01:00
<para>
If an extension has secondary control files, the control parameters
that are used for an update script are those associated with the script's
target (new) version.
</para>
2011-02-12 03:25:20 +01:00
<para>
The update mechanism can be used to solve an important special case:
2017-10-09 03:44:17 +02:00
converting a <quote>loose</quote> collection of objects into an extension.
2011-02-12 03:25:20 +01:00
Before the extension mechanism was added to
<productname>PostgreSQL</productname> (in 9.1), many people wrote
extension modules that simply created assorted unpackaged objects.
Given an existing database containing such objects, how can we convert
the objects into a properly packaged extension? Dropping them and then
2017-10-09 03:44:17 +02:00
doing a plain <command>CREATE EXTENSION</command> is one way, but it's not
2011-02-12 03:25:20 +01:00
desirable if the objects have dependencies (for example, if there are
table columns of a data type created by the extension). The way to fix
this situation is to create an empty extension, then use <command>ALTER
2017-10-09 03:44:17 +02:00
EXTENSION ADD</command> to attach each pre-existing object to the extension,
2011-02-12 03:25:20 +01:00
then finally create any new objects that are in the current extension
version but were not in the unpackaged release. <command>CREATE
2017-10-09 03:44:17 +02:00
EXTENSION</command> supports this case with its <literal>FROM</literal> <replaceable
class="parameter">old_version</replaceable> option, which causes it to not run the
2011-02-12 03:25:20 +01:00
normal installation script for the target version, but instead the update
script named
2017-10-09 03:44:17 +02:00
<literal><replaceable>extension</replaceable>--<replaceable>old_version</replaceable>--<replaceable>target_version</replaceable>.sql</literal>.
2011-02-12 03:25:20 +01:00
The choice of the dummy version name to use as <replaceable
2017-10-09 03:44:17 +02:00
class="parameter">old_version</replaceable> is up to the extension author, though
<literal>unpackaged</literal> is a common convention. If you have multiple
2011-02-12 03:25:20 +01:00
prior versions you need to be able to update into extension style, use
multiple dummy version names to identify them.
</para>
<para>
2017-10-09 03:44:17 +02:00
<command>ALTER EXTENSION</command> is able to execute sequences of update
2011-02-12 03:25:20 +01:00
script files to achieve a requested update. For example, if only
2017-10-09 03:44:17 +02:00
<literal>foo--1.0--1.1.sql</literal> and <literal>foo--1.1--2.0.sql</literal> are
available, <command>ALTER EXTENSION</command> will apply them in sequence if an
update to version <literal>2.0</literal> is requested when <literal>1.0</literal> is
2011-02-12 03:25:20 +01:00
currently installed.
</para>
<para>
2017-10-09 03:44:17 +02:00
<productname>PostgreSQL</productname> doesn't assume anything about the properties
of version names: for example, it does not know whether <literal>1.1</literal>
follows <literal>1.0</literal>. It just matches up the available version names
2011-02-12 03:25:20 +01:00
and follows the path that requires applying the fewest update scripts.
2011-02-13 19:03:41 +01:00
(A version name can actually be any string that doesn't contain
2017-10-09 03:44:17 +02:00
<literal>--</literal> or leading or trailing <literal>-</literal>.)
2011-02-12 03:25:20 +01:00
</para>
<para>
2017-10-09 03:44:17 +02:00
Sometimes it is useful to provide <quote>downgrade</quote> scripts, for
example <literal>foo--1.1--1.0.sql</literal> to allow reverting the changes
associated with version <literal>1.1</literal>. If you do that, be careful
2011-02-12 03:25:20 +01:00
of the possibility that a downgrade script might unexpectedly
get applied because it yields a shorter path. The risky case is where
2017-10-09 03:44:17 +02:00
there is a <quote>fast path</quote> update script that jumps ahead several
2011-02-12 03:25:20 +01:00
versions as well as a downgrade script to the fast path's start point.
It might take fewer steps to apply the downgrade and then the fast
path than to move ahead one version at a time. If the downgrade script
drops any irreplaceable objects, this will yield undesirable results.
</para>
2011-02-14 22:07:00 +01:00
<para>
To check for unexpected update paths, use this command:
<programlisting>
2017-10-09 03:44:17 +02:00
SELECT * FROM pg_extension_update_paths('<replaceable>extension_name</replaceable>');
2011-02-14 22:07:00 +01:00
</programlisting>
This shows each pair of distinct known version names for the specified
extension, together with the update path sequence that would be taken to
2017-10-09 03:44:17 +02:00
get from the source version to the target version, or <literal>NULL</literal> if
2011-02-14 22:07:00 +01:00
there is no available update path. The path is shown in textual form
2017-10-09 03:44:17 +02:00
with <literal>--</literal> separators. You can use
<literal>regexp_split_to_array(path,'--')</literal> if you prefer an array
2011-02-14 22:07:00 +01:00
format.
</para>
2011-02-12 03:25:20 +01:00
</sect2>
Allow CREATE EXTENSION to follow extension update paths.
Previously, to update an extension you had to produce both a version-update
script and a new base installation script. It's become more and more
obvious that that's tedious, duplicative, and error-prone. This patch
attempts to improve matters by allowing the new base installation script
to be omitted. CREATE EXTENSION will install a requested version if it
can find a base script and a chain of update scripts that will get there.
As in the existing update logic, shorter chains are preferred if there's
more than one possibility, with an arbitrary tie-break rule for chains
of equal length.
Also adjust the pg_available_extension_versions view to show such versions
as installable.
While at it, refactor the code so that CASCADE processing works for
extensions requested during ApplyExtensionUpdates(). Without this,
addition of a new requirement in an updated extension would require
creating a new base script, even if there was no other reason to do that.
(It would be easy at this point to add a CASCADE option to ALTER EXTENSION
UPDATE, to allow the same thing to happen during a manually-commanded
version update, but I have not done that here.)
Tom Lane, reviewed by Andres Freund
Discussion: <20160905005919.jz2m2yh3und2dsuy@alap3.anarazel.de>
2016-09-11 20:15:07 +02:00
<sect2>
<title>Installing Extensions using Update Scripts</title>
<para>
An extension that has been around for awhile will probably exist in
several versions, for which the author will need to write update scripts.
2017-10-09 03:44:17 +02:00
For example, if you have released a <literal>foo</literal> extension in
versions <literal>1.0</literal>, <literal>1.1</literal>, and <literal>1.2</literal>, there
should be update scripts <filename>foo--1.0--1.1.sql</filename>
and <filename>foo--1.1--1.2.sql</filename>.
Before <productname>PostgreSQL</productname> 10, it was necessary to also create
new script files <filename>foo--1.1.sql</filename> and <filename>foo--1.2.sql</filename>
Allow CREATE EXTENSION to follow extension update paths.
Previously, to update an extension you had to produce both a version-update
script and a new base installation script. It's become more and more
obvious that that's tedious, duplicative, and error-prone. This patch
attempts to improve matters by allowing the new base installation script
to be omitted. CREATE EXTENSION will install a requested version if it
can find a base script and a chain of update scripts that will get there.
As in the existing update logic, shorter chains are preferred if there's
more than one possibility, with an arbitrary tie-break rule for chains
of equal length.
Also adjust the pg_available_extension_versions view to show such versions
as installable.
While at it, refactor the code so that CASCADE processing works for
extensions requested during ApplyExtensionUpdates(). Without this,
addition of a new requirement in an updated extension would require
creating a new base script, even if there was no other reason to do that.
(It would be easy at this point to add a CASCADE option to ALTER EXTENSION
UPDATE, to allow the same thing to happen during a manually-commanded
version update, but I have not done that here.)
Tom Lane, reviewed by Andres Freund
Discussion: <20160905005919.jz2m2yh3und2dsuy@alap3.anarazel.de>
2016-09-11 20:15:07 +02:00
that directly build the newer extension versions, or else the newer
versions could not be installed directly, only by
2017-10-09 03:44:17 +02:00
installing <literal>1.0</literal> and then updating. That was tedious and
Allow CREATE EXTENSION to follow extension update paths.
Previously, to update an extension you had to produce both a version-update
script and a new base installation script. It's become more and more
obvious that that's tedious, duplicative, and error-prone. This patch
attempts to improve matters by allowing the new base installation script
to be omitted. CREATE EXTENSION will install a requested version if it
can find a base script and a chain of update scripts that will get there.
As in the existing update logic, shorter chains are preferred if there's
more than one possibility, with an arbitrary tie-break rule for chains
of equal length.
Also adjust the pg_available_extension_versions view to show such versions
as installable.
While at it, refactor the code so that CASCADE processing works for
extensions requested during ApplyExtensionUpdates(). Without this,
addition of a new requirement in an updated extension would require
creating a new base script, even if there was no other reason to do that.
(It would be easy at this point to add a CASCADE option to ALTER EXTENSION
UPDATE, to allow the same thing to happen during a manually-commanded
version update, but I have not done that here.)
Tom Lane, reviewed by Andres Freund
Discussion: <20160905005919.jz2m2yh3und2dsuy@alap3.anarazel.de>
2016-09-11 20:15:07 +02:00
duplicative, but now it's unnecessary, because <command>CREATE
2017-10-09 03:44:17 +02:00
EXTENSION</command> can follow update chains automatically.
Allow CREATE EXTENSION to follow extension update paths.
Previously, to update an extension you had to produce both a version-update
script and a new base installation script. It's become more and more
obvious that that's tedious, duplicative, and error-prone. This patch
attempts to improve matters by allowing the new base installation script
to be omitted. CREATE EXTENSION will install a requested version if it
can find a base script and a chain of update scripts that will get there.
As in the existing update logic, shorter chains are preferred if there's
more than one possibility, with an arbitrary tie-break rule for chains
of equal length.
Also adjust the pg_available_extension_versions view to show such versions
as installable.
While at it, refactor the code so that CASCADE processing works for
extensions requested during ApplyExtensionUpdates(). Without this,
addition of a new requirement in an updated extension would require
creating a new base script, even if there was no other reason to do that.
(It would be easy at this point to add a CASCADE option to ALTER EXTENSION
UPDATE, to allow the same thing to happen during a manually-commanded
version update, but I have not done that here.)
Tom Lane, reviewed by Andres Freund
Discussion: <20160905005919.jz2m2yh3und2dsuy@alap3.anarazel.de>
2016-09-11 20:15:07 +02:00
For example, if only the script
2017-10-09 03:44:17 +02:00
files <filename>foo--1.0.sql</filename>, <filename>foo--1.0--1.1.sql</filename>,
and <filename>foo--1.1--1.2.sql</filename> are available then a request to
install version <literal>1.2</literal> is honored by running those three
Allow CREATE EXTENSION to follow extension update paths.
Previously, to update an extension you had to produce both a version-update
script and a new base installation script. It's become more and more
obvious that that's tedious, duplicative, and error-prone. This patch
attempts to improve matters by allowing the new base installation script
to be omitted. CREATE EXTENSION will install a requested version if it
can find a base script and a chain of update scripts that will get there.
As in the existing update logic, shorter chains are preferred if there's
more than one possibility, with an arbitrary tie-break rule for chains
of equal length.
Also adjust the pg_available_extension_versions view to show such versions
as installable.
While at it, refactor the code so that CASCADE processing works for
extensions requested during ApplyExtensionUpdates(). Without this,
addition of a new requirement in an updated extension would require
creating a new base script, even if there was no other reason to do that.
(It would be easy at this point to add a CASCADE option to ALTER EXTENSION
UPDATE, to allow the same thing to happen during a manually-commanded
version update, but I have not done that here.)
Tom Lane, reviewed by Andres Freund
Discussion: <20160905005919.jz2m2yh3und2dsuy@alap3.anarazel.de>
2016-09-11 20:15:07 +02:00
scripts in sequence. The processing is the same as if you'd first
2017-10-09 03:44:17 +02:00
installed <literal>1.0</literal> and then updated to <literal>1.2</literal>.
(As with <command>ALTER EXTENSION UPDATE</command>, if multiple pathways are
Allow CREATE EXTENSION to follow extension update paths.
Previously, to update an extension you had to produce both a version-update
script and a new base installation script. It's become more and more
obvious that that's tedious, duplicative, and error-prone. This patch
attempts to improve matters by allowing the new base installation script
to be omitted. CREATE EXTENSION will install a requested version if it
can find a base script and a chain of update scripts that will get there.
As in the existing update logic, shorter chains are preferred if there's
more than one possibility, with an arbitrary tie-break rule for chains
of equal length.
Also adjust the pg_available_extension_versions view to show such versions
as installable.
While at it, refactor the code so that CASCADE processing works for
extensions requested during ApplyExtensionUpdates(). Without this,
addition of a new requirement in an updated extension would require
creating a new base script, even if there was no other reason to do that.
(It would be easy at this point to add a CASCADE option to ALTER EXTENSION
UPDATE, to allow the same thing to happen during a manually-commanded
version update, but I have not done that here.)
Tom Lane, reviewed by Andres Freund
Discussion: <20160905005919.jz2m2yh3und2dsuy@alap3.anarazel.de>
2016-09-11 20:15:07 +02:00
available then the shortest is preferred.) Arranging an extension's
script files in this style can reduce the amount of maintenance effort
needed to produce small updates.
</para>
<para>
If you use secondary (version-specific) control files with an extension
maintained in this style, keep in mind that each version needs a control
file even if it has no stand-alone installation script, as that control
file will determine how the implicit update to that version is performed.
2017-10-09 03:44:17 +02:00
For example, if <filename>foo--1.0.control</filename> specifies <literal>requires
= 'bar'</literal> but <literal>foo</literal>'s other control files do not, the
extension's dependency on <literal>bar</literal> will be dropped when updating
from <literal>1.0</literal> to another version.
Allow CREATE EXTENSION to follow extension update paths.
Previously, to update an extension you had to produce both a version-update
script and a new base installation script. It's become more and more
obvious that that's tedious, duplicative, and error-prone. This patch
attempts to improve matters by allowing the new base installation script
to be omitted. CREATE EXTENSION will install a requested version if it
can find a base script and a chain of update scripts that will get there.
As in the existing update logic, shorter chains are preferred if there's
more than one possibility, with an arbitrary tie-break rule for chains
of equal length.
Also adjust the pg_available_extension_versions view to show such versions
as installable.
While at it, refactor the code so that CASCADE processing works for
extensions requested during ApplyExtensionUpdates(). Without this,
addition of a new requirement in an updated extension would require
creating a new base script, even if there was no other reason to do that.
(It would be easy at this point to add a CASCADE option to ALTER EXTENSION
UPDATE, to allow the same thing to happen during a manually-commanded
version update, but I have not done that here.)
Tom Lane, reviewed by Andres Freund
Discussion: <20160905005919.jz2m2yh3und2dsuy@alap3.anarazel.de>
2016-09-11 20:15:07 +02:00
</para>
</sect2>
2016-09-07 19:36:08 +02:00
<sect2 id="extend-extensions-example">
2011-02-08 22:08:41 +01:00
<title>Extension Example</title>
<para>
2017-10-09 03:44:17 +02:00
Here is a complete example of an <acronym>SQL</acronym>-only
2011-02-08 22:08:41 +01:00
extension, a two-element composite type that can store any type of value
2017-10-09 03:44:17 +02:00
in its slots, which are named <quote>k</quote> and <quote>v</quote>. Non-text
2011-02-08 22:08:41 +01:00
values are automatically coerced to text for storage.
</para>
<para>
2017-10-09 03:44:17 +02:00
The script file <filename>pair--1.0.sql</filename> looks like this:
2011-02-08 22:08:41 +01:00
<programlisting><![CDATA[
2011-10-12 21:45:03 +02:00
-- complain if script is sourced in psql, rather than via CREATE EXTENSION
\echo Use "CREATE EXTENSION pair" to load this file. \quit
2018-03-24 04:31:03 +01:00
CREATE TYPE pair AS ( k text, v text );
2011-02-08 22:08:41 +01:00
2018-03-24 04:31:03 +01:00
CREATE OR REPLACE FUNCTION pair(text, text)
Document security implications of search_path and the public schema.
The ability to create like-named objects in different schemas opens up
the potential for users to change the behavior of other users' queries,
maliciously or accidentally. When you connect to a PostgreSQL server,
you should remove from your search_path any schema for which a user
other than yourself or superusers holds the CREATE privilege. If you do
not, other users holding CREATE privilege can redefine the behavior of
your commands, causing them to perform arbitrary SQL statements under
your identity. "SET search_path = ..." and "SELECT
pg_catalog.set_config(...)" are not vulnerable to such hijacking, so one
can use either as the first command of a session. As special
exceptions, the following client applications behave as documented
regardless of search_path settings and schema privileges: clusterdb
createdb createlang createuser dropdb droplang dropuser ecpg (not
programs it generates) initdb oid2name pg_archivecleanup pg_basebackup
pg_config pg_controldata pg_ctl pg_dump pg_dumpall pg_isready
pg_receivewal pg_recvlogical pg_resetwal pg_restore pg_rewind pg_standby
pg_test_fsync pg_test_timing pg_upgrade pg_waldump reindexdb vacuumdb
vacuumlo. Not included are core client programs that run user-specified
SQL commands, namely psql and pgbench. PostgreSQL encourages non-core
client applications to do likewise.
Document this in the context of libpq connections, psql connections,
dblink connections, ECPG connections, extension packaging, and schema
usage patterns. The principal defense for applications is "SELECT
pg_catalog.set_config('search_path', '', false)", and the principal
defense for databases is "REVOKE CREATE ON SCHEMA public FROM PUBLIC".
Either one is sufficient to prevent attack. After a REVOKE, consider
auditing the public schema for objects named like pg_catalog objects.
Authors of SECURITY DEFINER functions use some of the same defenses, and
the CREATE FUNCTION reference page already covered them thoroughly.
This is a good opportunity to audit SECURITY DEFINER functions for
robust security practice.
Back-patch to 9.3 (all supported versions).
Reviewed by Michael Paquier and Jonathan S. Katz. Reported by Arseniy
Sharoglazov.
Security: CVE-2018-1058
2018-02-26 16:39:44 +01:00
RETURNS pair LANGUAGE SQL AS 'SELECT ROW($1, $2)::@extschema@.pair;';
2011-02-08 22:08:41 +01:00
2018-08-15 18:05:46 +02:00
CREATE OPERATOR ~> (LEFTARG = text, RIGHTARG = text, FUNCTION = pair);
2011-02-08 22:08:41 +01:00
Document security implications of search_path and the public schema.
The ability to create like-named objects in different schemas opens up
the potential for users to change the behavior of other users' queries,
maliciously or accidentally. When you connect to a PostgreSQL server,
you should remove from your search_path any schema for which a user
other than yourself or superusers holds the CREATE privilege. If you do
not, other users holding CREATE privilege can redefine the behavior of
your commands, causing them to perform arbitrary SQL statements under
your identity. "SET search_path = ..." and "SELECT
pg_catalog.set_config(...)" are not vulnerable to such hijacking, so one
can use either as the first command of a session. As special
exceptions, the following client applications behave as documented
regardless of search_path settings and schema privileges: clusterdb
createdb createlang createuser dropdb droplang dropuser ecpg (not
programs it generates) initdb oid2name pg_archivecleanup pg_basebackup
pg_config pg_controldata pg_ctl pg_dump pg_dumpall pg_isready
pg_receivewal pg_recvlogical pg_resetwal pg_restore pg_rewind pg_standby
pg_test_fsync pg_test_timing pg_upgrade pg_waldump reindexdb vacuumdb
vacuumlo. Not included are core client programs that run user-specified
SQL commands, namely psql and pgbench. PostgreSQL encourages non-core
client applications to do likewise.
Document this in the context of libpq connections, psql connections,
dblink connections, ECPG connections, extension packaging, and schema
usage patterns. The principal defense for applications is "SELECT
pg_catalog.set_config('search_path', '', false)", and the principal
defense for databases is "REVOKE CREATE ON SCHEMA public FROM PUBLIC".
Either one is sufficient to prevent attack. After a REVOKE, consider
auditing the public schema for objects named like pg_catalog objects.
Authors of SECURITY DEFINER functions use some of the same defenses, and
the CREATE FUNCTION reference page already covered them thoroughly.
This is a good opportunity to audit SECURITY DEFINER functions for
robust security practice.
Back-patch to 9.3 (all supported versions).
Reviewed by Michael Paquier and Jonathan S. Katz. Reported by Arseniy
Sharoglazov.
Security: CVE-2018-1058
2018-02-26 16:39:44 +01:00
-- "SET search_path" is easy to get right, but qualified names perform better.
CREATE OR REPLACE FUNCTION lower(pair)
RETURNS pair LANGUAGE SQL
AS 'SELECT ROW(lower($1.k), lower($1.v))::@extschema@.pair;'
SET search_path = pg_temp;
2011-02-08 22:08:41 +01:00
Document security implications of search_path and the public schema.
The ability to create like-named objects in different schemas opens up
the potential for users to change the behavior of other users' queries,
maliciously or accidentally. When you connect to a PostgreSQL server,
you should remove from your search_path any schema for which a user
other than yourself or superusers holds the CREATE privilege. If you do
not, other users holding CREATE privilege can redefine the behavior of
your commands, causing them to perform arbitrary SQL statements under
your identity. "SET search_path = ..." and "SELECT
pg_catalog.set_config(...)" are not vulnerable to such hijacking, so one
can use either as the first command of a session. As special
exceptions, the following client applications behave as documented
regardless of search_path settings and schema privileges: clusterdb
createdb createlang createuser dropdb droplang dropuser ecpg (not
programs it generates) initdb oid2name pg_archivecleanup pg_basebackup
pg_config pg_controldata pg_ctl pg_dump pg_dumpall pg_isready
pg_receivewal pg_recvlogical pg_resetwal pg_restore pg_rewind pg_standby
pg_test_fsync pg_test_timing pg_upgrade pg_waldump reindexdb vacuumdb
vacuumlo. Not included are core client programs that run user-specified
SQL commands, namely psql and pgbench. PostgreSQL encourages non-core
client applications to do likewise.
Document this in the context of libpq connections, psql connections,
dblink connections, ECPG connections, extension packaging, and schema
usage patterns. The principal defense for applications is "SELECT
pg_catalog.set_config('search_path', '', false)", and the principal
defense for databases is "REVOKE CREATE ON SCHEMA public FROM PUBLIC".
Either one is sufficient to prevent attack. After a REVOKE, consider
auditing the public schema for objects named like pg_catalog objects.
Authors of SECURITY DEFINER functions use some of the same defenses, and
the CREATE FUNCTION reference page already covered them thoroughly.
This is a good opportunity to audit SECURITY DEFINER functions for
robust security practice.
Back-patch to 9.3 (all supported versions).
Reviewed by Michael Paquier and Jonathan S. Katz. Reported by Arseniy
Sharoglazov.
Security: CVE-2018-1058
2018-02-26 16:39:44 +01:00
CREATE OR REPLACE 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;';
2011-02-08 22:08:41 +01:00
]]>
</programlisting>
</para>
<para>
2017-10-09 03:44:17 +02:00
The control file <filename>pair.control</filename> looks like this:
2011-02-08 22:08:41 +01:00
<programlisting>
# pair extension
comment = 'A key/value pair data type'
2011-02-12 03:25:20 +01:00
default_version = '1.0'
Document security implications of search_path and the public schema.
The ability to create like-named objects in different schemas opens up
the potential for users to change the behavior of other users' queries,
maliciously or accidentally. When you connect to a PostgreSQL server,
you should remove from your search_path any schema for which a user
other than yourself or superusers holds the CREATE privilege. If you do
not, other users holding CREATE privilege can redefine the behavior of
your commands, causing them to perform arbitrary SQL statements under
your identity. "SET search_path = ..." and "SELECT
pg_catalog.set_config(...)" are not vulnerable to such hijacking, so one
can use either as the first command of a session. As special
exceptions, the following client applications behave as documented
regardless of search_path settings and schema privileges: clusterdb
createdb createlang createuser dropdb droplang dropuser ecpg (not
programs it generates) initdb oid2name pg_archivecleanup pg_basebackup
pg_config pg_controldata pg_ctl pg_dump pg_dumpall pg_isready
pg_receivewal pg_recvlogical pg_resetwal pg_restore pg_rewind pg_standby
pg_test_fsync pg_test_timing pg_upgrade pg_waldump reindexdb vacuumdb
vacuumlo. Not included are core client programs that run user-specified
SQL commands, namely psql and pgbench. PostgreSQL encourages non-core
client applications to do likewise.
Document this in the context of libpq connections, psql connections,
dblink connections, ECPG connections, extension packaging, and schema
usage patterns. The principal defense for applications is "SELECT
pg_catalog.set_config('search_path', '', false)", and the principal
defense for databases is "REVOKE CREATE ON SCHEMA public FROM PUBLIC".
Either one is sufficient to prevent attack. After a REVOKE, consider
auditing the public schema for objects named like pg_catalog objects.
Authors of SECURITY DEFINER functions use some of the same defenses, and
the CREATE FUNCTION reference page already covered them thoroughly.
This is a good opportunity to audit SECURITY DEFINER functions for
robust security practice.
Back-patch to 9.3 (all supported versions).
Reviewed by Michael Paquier and Jonathan S. Katz. Reported by Arseniy
Sharoglazov.
Security: CVE-2018-1058
2018-02-26 16:39:44 +01:00
relocatable = false
2011-02-08 22:08:41 +01:00
</programlisting>
</para>
<para>
While you hardly need a makefile to install these two files into the
2017-10-09 03:44:17 +02:00
correct directory, you could use a <filename>Makefile</filename> containing this:
2011-02-08 22:08:41 +01:00
<programlisting>
EXTENSION = pair
2011-02-13 19:03:41 +01:00
DATA = pair--1.0.sql
2011-02-08 22:08:41 +01:00
PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)
</programlisting>
This makefile relies on <acronym>PGXS</acronym>, which is described
2017-11-23 15:39:47 +01:00
in <xref linkend="extend-pgxs"/>. The command <literal>make install</literal>
2011-02-12 22:40:41 +01:00
will install the control and script files into the correct
2017-10-09 03:44:17 +02:00
directory as reported by <application>pg_config</application>.
2011-02-08 22:08:41 +01:00
</para>
<para>
Once the files are installed, use the
2017-11-23 15:39:47 +01:00
<xref linkend="sql-createextension"/> command to load the objects into
2011-02-08 22:08:41 +01:00
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
2017-10-09 03:44:17 +02:00
<productname>PostgreSQL</productname> extension modules, setting up a
2011-02-08 22:08:41 +01:00
portable build system for them can be fairly difficult. Therefore
2017-10-09 03:44:17 +02:00
the <productname>PostgreSQL</productname> installation provides a build
2011-02-08 22:08:41 +01:00
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
2017-10-09 03:44:17 +02:00
to build any software interfacing to <productname>PostgreSQL</productname>;
2011-02-08 22:08:41 +01:00
it simply automates common build rules for simple server extension
modules. For more complicated packages, you might need to write your
own build system.
2010-06-01 04:31:36 +02:00
</para>
2010-06-03 16:39:58 +02:00
<para>
2011-02-08 22:08:41 +01:00
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
2013-10-07 04:57:16 +02:00
and include the global <acronym>PGXS</acronym> makefile.
2011-02-08 22:08:41 +01:00
Here is an example that builds an extension module named
<literal>isbn_issn</literal>, consisting of a shared library containing
2018-07-31 20:58:39 +02:00
some C code, an extension control file, a SQL script, an include file
(only needed if other modules might need to access the extension functions
without going via SQL), and a documentation text file:
2011-02-08 22:08:41 +01:00
<programlisting>
MODULES = isbn_issn
EXTENSION = isbn_issn
2011-02-13 19:03:41 +01:00
DATA = isbn_issn--1.0.sql
2011-02-08 22:08:41 +01:00
DOCS = README.isbn_issn
2018-07-31 20:58:39 +02:00
HEADERS_isbn_issn = isbn_issn.h
2011-02-08 22:08:41 +01:00
PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)
</programlisting>
The last three lines should always be the same. Earlier in the
file, you assign variables or add custom
<application>make</application> rules.
2010-06-03 16:39:58 +02:00
</para>
2011-02-08 22:08:41 +01:00
<para>
Set one of these three variables to specify what is built:
<variablelist>
<varlistentry>
<term><varname>MODULES</varname></term>
<listitem>
<para>
list of shared-library objects to be built from source files with same
stem (do not include library suffixes in this list)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>MODULE_big</varname></term>
<listitem>
<para>
a shared library to build from multiple source files
(list object files in <varname>OBJS</varname>)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>PROGRAM</varname></term>
<listitem>
<para>
an executable program to build
(list object files in <varname>OBJS</varname>)
</para>
</listitem>
</varlistentry>
</variablelist>
The following variables can also be set:
<variablelist>
<varlistentry>
2011-02-12 04:53:43 +01:00
<term><varname>EXTENSION</varname></term>
2011-02-08 22:08:41 +01:00
<listitem>
<para>
2011-02-12 04:53:43 +01:00
extension name(s); for each name you must provide an
<literal><replaceable>extension</replaceable>.control</literal> file,
which will be installed into
<literal><replaceable>prefix</replaceable>/share/extension</literal>
2011-02-08 22:08:41 +01:00
</para>
</listitem>
</varlistentry>
<varlistentry>
2011-02-12 04:53:43 +01:00
<term><varname>MODULEDIR</varname></term>
2011-02-08 22:08:41 +01:00
<listitem>
<para>
2017-10-09 03:44:17 +02:00
subdirectory of <literal><replaceable>prefix</replaceable>/share</literal>
2011-02-12 04:53:43 +01:00
into which DATA and DOCS files should be installed
(if not set, default is <literal>extension</literal> if
<varname>EXTENSION</varname> is set,
or <literal>contrib</literal> if not)
2011-02-08 22:08:41 +01:00
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>DATA</varname></term>
<listitem>
<para>
random files to install into <literal><replaceable>prefix</replaceable>/share/$MODULEDIR</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>DATA_built</varname></term>
<listitem>
<para>
random files to install into
<literal><replaceable>prefix</replaceable>/share/$MODULEDIR</literal>,
which need to be built first
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>DATA_TSEARCH</varname></term>
<listitem>
<para>
random files to install under
<literal><replaceable>prefix</replaceable>/share/tsearch_data</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>DOCS</varname></term>
<listitem>
<para>
random files to install under
<literal><replaceable>prefix</replaceable>/doc/$MODULEDIR</literal>
</para>
</listitem>
</varlistentry>
2018-07-31 20:58:39 +02:00
<varlistentry>
<term><varname>HEADERS</varname></term>
2018-09-05 23:01:21 +02:00
<term><varname>HEADERS_built</varname></term>
2018-07-31 20:58:39 +02:00
<listitem>
<para>
2018-09-07 14:51:30 +02:00
Files to (optionally build and) install under
<literal><replaceable>prefix</replaceable>/include/server/$MODULEDIR/$MODULE_big</literal>.
</para>
<para>
Unlike <literal>DATA_built</literal>, files in <literal>HEADERS_built</literal>
are not removed by the <literal>clean</literal> target; if you want them removed,
also add them to <literal>EXTRA_CLEAN</literal> or add your own rules to do it.
2018-07-31 20:58:39 +02:00
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>HEADERS_$MODULE</varname></term>
2018-09-05 23:01:21 +02:00
<term><varname>HEADERS_built_$MODULE</varname></term>
2018-07-31 20:58:39 +02:00
<listitem>
<para>
2018-09-05 23:01:21 +02:00
Files to install (after building if specified) under
2018-07-31 20:58:39 +02:00
<literal><replaceable>prefix</replaceable>/include/server/$MODULEDIR/$MODULE</literal>,
where <literal>$MODULE</literal> must be a module name used
2018-09-05 23:01:21 +02:00
in <literal>MODULES</literal> or <literal>MODULE_big</literal>.
</para>
2018-09-07 14:51:30 +02:00
<para>
Unlike <literal>DATA_built</literal>, files in <literal>HEADERS_built_$MODULE</literal>
are not removed by the <literal>clean</literal> target; if you want them removed,
also add them to <literal>EXTRA_CLEAN</literal> or add your own rules to do it.
</para>
2018-09-05 23:01:21 +02:00
<para>
It is legal to use both variables for the same module, or any
combination, unless you have two module names in the
<literal>MODULES</literal> list that differ only by the presence of a
prefix <literal>built_</literal>, which would cause ambiguity. In
that (hopefully unlikely) case, you should use only the
<literal>HEADERS_built_$MODULE</literal> variables.
2018-07-31 20:58:39 +02:00
</para>
</listitem>
</varlistentry>
2011-02-08 22:08:41 +01:00
<varlistentry>
<term><varname>SCRIPTS</varname></term>
<listitem>
<para>
script files (not binaries) to install into
<literal><replaceable>prefix</replaceable>/bin</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>SCRIPTS_built</varname></term>
<listitem>
<para>
script files (not binaries) to install into
<literal><replaceable>prefix</replaceable>/bin</literal>,
which need to be built first
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>REGRESS</varname></term>
<listitem>
<para>
list of regression test cases (without suffix), see below
</para>
</listitem>
</varlistentry>
2011-08-24 21:16:17 +02:00
<varlistentry>
<term><varname>REGRESS_OPTS</varname></term>
<listitem>
<para>
2017-10-09 03:44:17 +02:00
additional switches to pass to <application>pg_regress</application>
2011-08-24 21:16:17 +02:00
</para>
</listitem>
</varlistentry>
2016-11-14 23:53:07 +01:00
<varlistentry>
<term><varname>NO_INSTALLCHECK</varname></term>
<listitem>
<para>
2017-06-18 20:01:45 +02:00
don't define an <literal>installcheck</literal> target, useful e.g. if tests require special configuration, or don't use <application>pg_regress</application>
2016-11-14 23:53:07 +01:00
</para>
</listitem>
</varlistentry>
2011-02-08 22:08:41 +01:00
<varlistentry>
<term><varname>EXTRA_CLEAN</varname></term>
<listitem>
<para>
extra files to remove in <literal>make clean</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>PG_CPPFLAGS</varname></term>
<listitem>
<para>
will be added to <varname>CPPFLAGS</varname>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>PG_LIBS</varname></term>
<listitem>
<para>
will be added to <varname>PROGRAM</varname> link line
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>SHLIB_LINK</varname></term>
<listitem>
<para>
will be added to <varname>MODULE_big</varname> link line
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>PG_CONFIG</varname></term>
<listitem>
<para>
2017-10-09 03:44:17 +02:00
path to <application>pg_config</application> program for the
2011-02-08 22:08:41 +01:00
<productname>PostgreSQL</productname> installation to build against
2017-10-09 03:44:17 +02:00
(typically just <literal>pg_config</literal> to use the first one in your
<varname>PATH</varname>)
2011-02-08 22:08:41 +01:00
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Put this makefile as <literal>Makefile</literal> in the directory
which holds your extension. Then you can do
<literal>make</literal> to compile, and then <literal>make
install</literal> to install your module. By default, the extension is
compiled and installed for the
<productname>PostgreSQL</productname> installation that
corresponds to the first <command>pg_config</command> program
2017-10-09 03:44:17 +02:00
found in your <varname>PATH</varname>. You can use a different installation by
2011-02-08 22:08:41 +01:00
setting <varname>PG_CONFIG</varname> to point to its
<command>pg_config</command> program, either within the makefile
or on the <literal>make</literal> command line.
</para>
2013-10-07 04:57:16 +02:00
<para>
You can also run <literal>make</literal> in a directory outside the source
tree of your extension, if you want to keep the build directory separate.
This procedure is also called a
<indexterm><primary>VPATH</primary></indexterm><firstterm>VPATH</firstterm>
build. Here's how:
2014-07-08 17:39:07 +02:00
<programlisting>
mkdir build_dir
cd build_dir
make -f /path/to/extension/source/tree/Makefile
make -f /path/to/extension/source/tree/Makefile install
</programlisting>
2013-10-07 04:57:16 +02:00
</para>
<para>
Alternatively, you can set up a directory for a VPATH build in a similar
2013-12-13 18:58:48 +01:00
way to how it is done for the core code. One way to do this is using the
2017-10-09 03:44:17 +02:00
core script <filename>config/prep_buildtree</filename>. Once this has been done
2013-10-07 04:57:16 +02:00
you can build by setting the <literal>make</literal> variable
2014-11-20 03:51:30 +01:00
<varname>VPATH</varname> like this:
2014-07-08 17:39:07 +02:00
<programlisting>
2014-11-20 03:51:30 +01:00
make VPATH=/path/to/extension/source/tree
make VPATH=/path/to/extension/source/tree install
2014-07-08 17:39:07 +02:00
</programlisting>
2013-10-07 04:57:16 +02:00
This procedure can work with a greater variety of directory layouts.
</para>
2011-02-08 22:08:41 +01:00
<para>
2017-10-09 03:44:17 +02:00
The scripts listed in the <varname>REGRESS</varname> variable are used for
2011-02-08 22:08:41 +01:00
regression testing of your module, which can be invoked by <literal>make
2017-10-09 03:44:17 +02:00
installcheck</literal> after doing <literal>make install</literal>. For this to
2011-02-08 22:08:41 +01:00
work you must have a running <productname>PostgreSQL</productname> server.
2017-10-09 03:44:17 +02:00
The script files listed in <varname>REGRESS</varname> must appear in a
2011-02-08 22:08:41 +01:00
subdirectory named <literal>sql/</literal> in your extension's directory.
These files must have extension <literal>.sql</literal>, which must not be
included in the <varname>REGRESS</varname> list in the makefile. For each
test there should also be a file containing the expected output in a
subdirectory named <literal>expected/</literal>, with the same stem and
extension <literal>.out</literal>. <literal>make installcheck</literal>
2017-10-09 03:44:17 +02:00
executes each test script with <application>psql</application>, and compares the
2011-02-08 22:08:41 +01:00
resulting output to the matching expected file. Any differences will be
written to the file <literal>regression.diffs</literal> in <command>diff
-c</command> format. Note that trying to run a test that is missing its
expected file will be reported as <quote>trouble</quote>, so make sure you
have all expected files.
</para>
<tip>
<para>
The easiest way to create the expected files is to create empty files,
then do a test run (which will of course report differences). Inspect
the actual result files found in the <literal>results/</literal>
2018-11-26 03:12:11 +01:00
directory, then copy them to <literal>expected/</literal> if they match
what you expect from the test.
2011-02-08 22:08:41 +01:00
</para>
</tip>
2010-06-01 04:31:36 +02:00
</sect1>
1999-07-22 17:11:05 +02:00
</chapter>