Dimitri, * Dimitri Fontaine (dimi...@2ndquadrant.fr) wrote: > As the path didn't make it already, yes it needs another (final) round > of review. The main difficulty in reviewing is understanding the design > and the relation in between our current model of extensions and what > this patch offers.
I'm afraid this really needs more work, at least of the more mundane kind. I started working through this patch, but when I hit on "get_template_oid", I was reminded of the discussion we had back in January around using just 'template' everywhere. http://www.postgresql.org/message-id/20130118182156.gf16...@tamriel.snowman.net We already have other 'template' objects in the system and I'm not excited about the confusion. This also applies to 'CreateTemplate', 'CreateTemplateTupleDesc', right down to 'template.h' and 'template.c'. Attached is a patch against v16 which fixes up a few documentation issues (I'm pretty sure extension templates and aggregates are unrelated..), and points out that there is zero documentation on these new catalog tables (look for 'XXX' in the patch) along with a few other areas which could use improvement. Thanks, Stephen
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
new file mode 100644
index acc261c..ae1ce2e 100644
*** a/doc/src/sgml/catalogs.sgml
--- b/doc/src/sgml/catalogs.sgml
***************
*** 154,159 ****
--- 154,174 ----
</row>
<row>
+ <entry><link linkend="catalog-pg-extension-control"><structname>pg_extension_control</structname></link></entry>
+ <XXX>Needs documentation</XXX>
+ </row>
+
+ <row>
+ <entry><link linkend="catalog-pg-extension-template"><structname>pg_extension_template</structname></link></entry>
+ <XXX>Needs documentation</XXX>
+ </row>
+
+ <row>
+ <entry><link linkend="catalog-pg-extension-uptmpl"><structname>pg_extension_uptmpl</structname></link></entry>
+ <XXX>Needs documentation</XXX>
+ </row>
+
+ <row>
<entry><link linkend="catalog-pg-foreign-data-wrapper"><structname>pg_foreign_data_wrapper</structname></link></entry>
<entry>foreign-data wrapper definitions</entry>
</row>
***************
*** 3290,3295 ****
--- 3305,3325 ----
</para>
</sect1>
+ <sect1 id="catalog-pg-extension-control">
+ <title><structname>pg_extension_control</structname></title>
+ <XXX>Needs documentation</XXX>
+ </sect1>
+
+ <sect1 id="catalog-pg-extension-template">
+ <title><structname>pg_extension_template</structname></title>
+ <XXX>Needs documentation</XXX>
+ </sect1>
+
+ <sect1 id="catalog-pg-extension-uptmpl">
+ <title><structname>pg_extension_uptmpl</structname></title>
+ <XXX>Needs documentation</XXX>
+ </sect1>
+
<sect1 id="catalog-pg-foreign-data-wrapper">
<title><structname>pg_foreign_data_wrapper</structname></title>
diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
new file mode 100644
index 772310b..b4a589c 100644
*** a/doc/src/sgml/extend.sgml
--- b/doc/src/sgml/extend.sgml
***************
*** 384,398 ****
<para>
The <xref linkend="sql-create-template-for-extension"> command allows a
! superuser to create an <firstterm>Extension's Template</>, that users
will then be able to use as the source for their script and control
parameters. Upgrade scripts can be provided with the same command, and
! those upgrade scripts can include parameters update too, as would a
secondary control file.
</para>
<para>
! Here's a very simple example at using a template for an extension:
<programlisting>
create template for extension myextension version '1.0' with (nosuperuser) as
$script$
--- 384,398 ----
<para>
The <xref linkend="sql-create-template-for-extension"> command allows a
! superuser to create an <firstterm>Extension Template</>, that users
will then be able to use as the source for their script and control
parameters. Upgrade scripts can be provided with the same command, and
! those upgrade scripts can include parameter updates too, as would a
secondary control file.
</para>
<para>
! Here's a very simple example of using a template for an extension:
<programlisting>
create template for extension myextension version '1.0' with (nosuperuser) as
$script$
*************** create extension myextension;
*** 476,487 ****
<listitem>
<para>
This option allows an extension author to avoid shiping all versions
! scripts when shipping an extension. When a version is requested and
! the matching script does not exist on disk,
set <replaceable>default_full_version</replaceable> to the first
script you still ship and PostgreSQL will apply the intermediate
upgrade script as per the <command>ALTER EXTENSION UPDATE</command>
command.
</para>
</listitem>
</varlistentry>
--- 476,488 ----
<listitem>
<para>
This option allows an extension author to avoid shiping all versions
! of all scripts when shipping an extension. When a version is requested
! and the matching script does not exist on disk,
set <replaceable>default_full_version</replaceable> to the first
script you still ship and PostgreSQL will apply the intermediate
upgrade script as per the <command>ALTER EXTENSION UPDATE</command>
command.
+ <XXX> EXAMPLE NEEDED </XXX>
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/alter_extension_template.sgml b/doc/src/sgml/ref/alter_extension_template.sgml
new file mode 100644
index 932c73f..527ef8b 100644
*** a/doc/src/sgml/ref/alter_extension_template.sgml
--- b/doc/src/sgml/ref/alter_extension_template.sgml
*************** ALTER TEMPLATE FOR EXTENSION <replaceabl
*** 46,52 ****
<para>
<command>ALTER TEMPLATE FOR EXTENSION</command> changes the definition of
! an extension template.
</para>
</refsect1>
--- 46,52 ----
<para>
<command>ALTER TEMPLATE FOR EXTENSION</command> changes the definition of
! an existing extension template.
</para>
</refsect1>
*************** ALTER TEMPLATE FOR EXTENSION <replaceabl
*** 79,85 ****
<para>
The version of the extension we want to install from by default when
using its template. For example, if you have an extension installation
! scipt for version <literal>1.0</literal> and an upgrade script
for <literal>1.0--1.1</literal>, you can set the
default <literal>full_version</literal> to <literal>1.0</literal> so
that <productname>PostgreSQL</productname> knows to install
--- 79,85 ----
<para>
The version of the extension we want to install from by default when
using its template. For example, if you have an extension installation
! script for version <literal>1.0</literal> and an upgrade script
for <literal>1.0--1.1</literal>, you can set the
default <literal>full_version</literal> to <literal>1.0</literal> so
that <productname>PostgreSQL</productname> knows to install
*************** ALTER TEMPLATE FOR EXTENSION <replaceabl
*** 113,119 ****
<term><replaceable class="parameter">new_name</replaceable></term>
<listitem>
<para>
! The new name of the aggregate function.
</para>
</listitem>
</varlistentry>
--- 113,119 ----
<term><replaceable class="parameter">new_name</replaceable></term>
<listitem>
<para>
! The new name of the extension template.
</para>
</listitem>
</varlistentry>
*************** ALTER TEMPLATE FOR EXTENSION <replaceabl
*** 122,128 ****
<term><replaceable class="parameter">new_owner</replaceable></term>
<listitem>
<para>
! The new owner of the aggregate function.
</para>
</listitem>
</varlistentry>
--- 122,128 ----
<term><replaceable class="parameter">new_owner</replaceable></term>
<listitem>
<para>
! The new owner of the extension template.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/create_extension_template.sgml b/doc/src/sgml/ref/create_extension_template.sgml
new file mode 100644
index 7fc7304..c8563df 100644
*** a/doc/src/sgml/ref/create_extension_template.sgml
--- b/doc/src/sgml/ref/create_extension_template.sgml
*************** PostgreSQL documentation
*** 12,18 ****
<refnamediv>
<refname>CREATE TEMPLATE FOR EXTENSION</refname>
! <refpurpose>define a new template for extension</refpurpose>
</refnamediv>
<indexterm zone="sql-create-template-for-extension">
--- 12,18 ----
<refnamediv>
<refname>CREATE TEMPLATE FOR EXTENSION</refname>
! <refpurpose>define a new template for an extension</refpurpose>
</refnamediv>
<indexterm zone="sql-create-template-for-extension">
*************** AS <replaceable class="parameter">script
*** 57,63 ****
<para>
Using the <command>CREATE TEMPLATE FOR EXTENSION</command> command you
! can upload script to be run at <command>CREATE EXTENSION</command> time
and at <command>ALTER EXTENSION ... UPDATE</command> time.
</para>
--- 57,63 ----
<para>
Using the <command>CREATE TEMPLATE FOR EXTENSION</command> command you
! can upload a script to be run at <command>CREATE EXTENSION</command> time
and at <command>ALTER EXTENSION ... UPDATE</command> time.
</para>
*************** AS <replaceable class="parameter">script
*** 76,95 ****
<variablelist>
<varlistentry>
! <term><varname>COMMENT</varname> (<type>string</type>)</term>
<listitem>
<para>
! See the <literal>comment</> control file parameter
in <xref linkend="extend-extensions">.
</para>
</listitem>
</varlistentry>
<varlistentry>
! <term><varname>REQUIRES</varname> (<type>string</type>)</term>
<listitem>
<para>
! See the <literal>requires</> control file parameter
in <xref linkend="extend-extensions">.
</para>
</listitem>
--- 76,95 ----
<variablelist>
<varlistentry>
! <term><varname>schema</varname> (<type>string</type>)</term>
<listitem>
<para>
! See the <literal>schema</> control file parameter
in <xref linkend="extend-extensions">.
</para>
</listitem>
</varlistentry>
<varlistentry>
! <term><varname>COMMENT</varname> (<type>string</type>)</term>
<listitem>
<para>
! See the <literal>comment</> control file parameter
in <xref linkend="extend-extensions">.
</para>
</listitem>
*************** AS <replaceable class="parameter">script
*** 140,149 ****
</varlistentry>
<varlistentry>
! <term><varname>schema</varname> (<type>string</type>)</term>
<listitem>
<para>
! See the <literal>schema</> control file parameter
in <xref linkend="extend-extensions">.
</para>
</listitem>
--- 140,149 ----
</varlistentry>
<varlistentry>
! <term><varname>REQUIRES</varname> (<type>string</type>)</term>
<listitem>
<para>
! See the <literal>requires</> control file parameter
in <xref linkend="extend-extensions">.
</para>
</listitem>
diff --git a/doc/src/sgml/ref/drop_extension_template.sgml b/doc/src/sgml/ref/drop_extension_template.sgml
new file mode 100644
index 5272014..1f2351c 100644
*** a/doc/src/sgml/ref/drop_extension_template.sgml
--- b/doc/src/sgml/ref/drop_extension_template.sgml
*************** PostgreSQL documentation
*** 31,37 ****
<para>
<command>DROP TEMPLATE FOR EXTENSION</command> drops an existing template
! for named extension
</para>
</refsect1>
--- 31,37 ----
<para>
<command>DROP TEMPLATE FOR EXTENSION</command> drops an existing template
! for the named extension
</para>
</refsect1>
*************** PostgreSQL documentation
*** 43,49 ****
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
! The name of an existing text search template.
</para>
</listitem>
</varlistentry>
--- 43,49 ----
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
! The name of an existing extension template.
</para>
</listitem>
</varlistentry>
*************** PostgreSQL documentation
*** 52,58 ****
<term><literal>CASCADE</literal></term>
<listitem>
<para>
! Automatically drop objects that depend on the template.
</para>
</listitem>
</varlistentry>
--- 52,58 ----
<term><literal>CASCADE</literal></term>
<listitem>
<para>
! Automatically drop objects that depend on the extension template.
</para>
</listitem>
</varlistentry>
*************** PostgreSQL documentation
*** 61,68 ****
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
! Refuse to drop the template if any objects depend on it. This is the
! default.
</para>
</listitem>
</varlistentry>
--- 61,68 ----
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
! Refuse to drop the extension template if any objects depend on it.
! This is the default.
</para>
</listitem>
</varlistentry>
diff --git a/src/backend/catalog/objectaddress.c b/src/backend/catalog/objectaddress.c
new file mode 100644
index 8320ee6..3f9b042 100644
*** a/src/backend/catalog/objectaddress.c
--- b/src/backend/catalog/objectaddress.c
*************** static ObjectAddress get_object_address_
*** 468,474 ****
List *objname, bool missing_ok);
static ObjectAddress get_object_address_opcf(ObjectType objtype, List *objname,
List *objargs, bool missing_ok);
! static ObjectAddress get_object_address_tmpl(ObjectType objtype,
List *objname, List *objargs, bool missing_ok);
static ObjectPropertyType *get_object_property_data(Oid class_id);
--- 468,474 ----
List *objname, bool missing_ok);
static ObjectAddress get_object_address_opcf(ObjectType objtype, List *objname,
List *objargs, bool missing_ok);
! static ObjectAddress get_object_address_exttmpl(ObjectType objtype,
List *objname, List *objargs, bool missing_ok);
static ObjectPropertyType *get_object_property_data(Oid class_id);
*************** get_object_address(ObjectType objtype, L
*** 562,569 ****
break;
case OBJECT_EXTENSION_TEMPLATE:
case OBJECT_EXTENSION_UPTMPL:
! address = get_object_address_tmpl(objtype,
! objname, objargs, missing_ok);
break;
case OBJECT_TYPE:
case OBJECT_DOMAIN:
--- 562,569 ----
break;
case OBJECT_EXTENSION_TEMPLATE:
case OBJECT_EXTENSION_UPTMPL:
! address = get_object_address_exttmpl(objtype, objname,
! objargs, missing_ok);
break;
case OBJECT_TYPE:
case OBJECT_DOMAIN:
*************** get_object_address_opcf(ObjectType objty
*** 1159,1170 ****
}
/*
! * Find the ObjectAddress for an extension template, control or update
! * template.
*/
static ObjectAddress
! get_object_address_tmpl(ObjectType objtype,
! List *objname, List *objargs, bool missing_ok)
{
const char *name;
ObjectAddress address;
--- 1159,1169 ----
}
/*
! * Find the ObjectAddress for an extension template or update template.
*/
static ObjectAddress
! get_object_address_exttmpl(ObjectType objtype,
! List *objname, List *objargs, bool missing_ok)
{
const char *name;
ObjectAddress address;
signature.asc
Description: Digital signature
