rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Doc: minor documentation improvements about extensions. 

Document the formerly-undocumented behavior that schema and comment
control-file entries for an extension are honored only during initial
installation, whereas other properties are also honored during updates.

While at it, do some copy-editing on the recently-added docs for CREATE
EXTENSION ... CASCADE, use links for some formerly vague cross references,
and make a couple other minor improvements.

Back-patch to 9.6 where CASCADE was added.  The other parts of this
could go further back, but they're probably not important enough to
bother.
This commit is contained in:
Tom Lane 2016-09-07 13:36:08 -04:00
parent 4f405c8ef4
commit bd180b6079
2 changed files with 42 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
doc/src/sgml/extend.sgml
View File

@ -335,11 +335,13 @@
by <application>pg_dump</>. Such a change is usually only sensible if by <application>pg_dump</>. Such a change is usually only sensible if
you concurrently make the same change in the extension's script file. you concurrently make the same change in the extension's script file.
(But there are special provisions for tables containing configuration (But there are special provisions for tables containing configuration
data; see below.) data; see <xref linkend="extend-extensions-config-tables">.)
In production situations, it's generally better to create an extension
update script to perform changes to extension member objects.
</para> </para>
<para> <para>
The extension script may set privileges on objects which are part of the The extension script may set privileges on objects that are part of the
extension via <command>GRANT</command> and <command>REVOKE</command> extension via <command>GRANT</command> and <command>REVOKE</command>
statements. The final set of privileges for each object (if any are set) statements. The final set of privileges for each object (if any are set)
will be stored in the will be stored in the
@ -453,9 +455,11 @@
<term><varname>comment</varname> (<type>string</type>)</term> <term><varname>comment</varname> (<type>string</type>)</term>
<listitem> <listitem>
<para> <para>
A comment (any string) about the extension. Alternatively, A comment (any string) about the extension. The comment is applied
the comment can be set by means of the <xref linkend="sql-comment"> when initially creating an extension, but not during extension updates
command in the script file. (since that might override user-added comments). Alternatively,
the extension's comment can be set by writing
a <xref linkend="sql-comment"> command in the script file.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -518,7 +522,7 @@
its contained objects into a different schema after initial creation its contained objects into a different schema after initial creation
of the extension. The default is <literal>false</>, i.e. the of the extension. The default is <literal>false</>, i.e. the
extension is not relocatable. extension is not relocatable.
See below for more information. See <xref linkend="extend-extensions-relocation"> for more information.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -529,7 +533,10 @@
<para> <para>
This parameter can only be set for non-relocatable extensions. This parameter can only be set for non-relocatable extensions.
It forces the extension to be loaded into exactly the named schema It forces the extension to be loaded into exactly the named schema
and not any other. See below for more information. and not any other.
The <varname>schema</varname> parameter is consulted only when
initially creating an extension, not during extension updates.
See <xref linkend="extend-extensions-relocation"> for more information.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -562,7 +569,8 @@
comments) by the extension mechanism. This provision is commonly used comments) by the extension mechanism. This provision is commonly used
to throw an error if the script file is fed to <application>psql</> to throw an error if the script file is fed to <application>psql</>
rather than being loaded via <command>CREATE EXTENSION</> (see example rather than being loaded via <command>CREATE EXTENSION</> (see example
script below). Without that, users might accidentally load the script in <xref linkend="extend-extensions-example">).
Without that, users might accidentally load the
extension's contents as <quote>loose</> objects rather than as an extension's contents as <quote>loose</> objects rather than as an
extension, a state of affairs that's a bit tedious to recover from. extension, a state of affairs that's a bit tedious to recover from.
</para> </para>
@ -580,7 +588,7 @@
</sect2> </sect2>
<sect2> <sect2 id="extend-extensions-relocation">
<title>Extension Relocatability</title> <title>Extension Relocatability</title>
<para> <para>
@ -678,7 +686,7 @@ SET LOCAL search_path TO @extschema@;
</para> </para>
</sect2> </sect2>
<sect2> <sect2 id="extend-extensions-config-tables">
<title>Extension Configuration Tables</title> <title>Extension Configuration Tables</title>
<para> <para>
@ -877,7 +885,7 @@ SELECT * FROM pg_extension_update_paths('<replaceable>extension_name</>');
</para> </para>
</sect2> </sect2>
<sect2> <sect2 id="extend-extensions-example">
<title>Extension Example</title> <title>Extension Example</title>
<para> <para>

54
doc/src/sgml/ref/create_extension.sgml
View File

@ -95,35 +95,21 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name
If not specified, and the extension's control file does not specify a If not specified, and the extension's control file does not specify a
schema either, the current default object creation schema is used. schema either, the current default object creation schema is used.
</para> </para>
<para> <para>
If the extension specifies <literal>schema</> in its control file, If the extension specifies a <literal>schema</> parameter in its
the schema cannot be overridden with <literal>SCHEMA</> clause. control file, then that schema cannot be overridden with
The <literal>SCHEMA</> clause in this case works as follows: a <literal>SCHEMA</> clause. Normally, an error will be raised if
<itemizedlist> a <literal>SCHEMA</> clause is given and it conflicts with the
<listitem> extension's <literal>schema</> parameter. However, if
<para> the <literal>CASCADE</> clause is also given,
If <replaceable class="parameter">schema_name</replaceable> matches then <replaceable class="parameter">schema_name</replaceable> is
the schema in control file, it will be used normally as there is no ignored when it conflicts. The
conflict. given <replaceable class="parameter">schema_name</replaceable> will be
</para> used for installation of any needed extensions that do not
</listitem> specify <literal>schema</> in their control files.
<listitem>
<para>
If the <literal>CASCADE</> clause is given, the
<replaceable class="parameter">schema_name</replaceable> will only
be used for the missing required extensions which do not specify
<literal>schema</> in their control files.
</para>
</listitem>
<listitem>
<para>
If <replaceable class="parameter">schema_name</replaceable> is not
the same as the one in extension's control file and the
<literal>CASCADE</> clause is not given, error will be thrown.
</para>
</listitem>
</itemizedlist>
</para> </para>
<para> <para>
Remember that the extension itself is not considered to be within any Remember that the extension itself is not considered to be within any
schema: extensions have unqualified names that must be unique schema: extensions have unqualified names that must be unique
@ -147,7 +133,8 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name
<varlistentry> <varlistentry>
<term><replaceable class="parameter">old_version</replaceable></term> <term><replaceable class="parameter">old_version</replaceable></term>
<listitem> <listitem>
<para><literal>FROM</> <replaceable class="parameter">old_version</> <para>
<literal>FROM</> <replaceable class="parameter">old_version</>
must be specified when, and only when, you are attempting to install must be specified when, and only when, you are attempting to install
an extension that replaces an <quote>old style</> module that is just an extension that replaces an <quote>old style</> module that is just
a collection of objects not packaged into an extension. This option a collection of objects not packaged into an extension. This option
@ -174,10 +161,13 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name
<term><literal>CASCADE</></term> <term><literal>CASCADE</></term>
<listitem> <listitem>
<para> <para>
Try to install extension including the required dependencies Automatically install any extensions that this extension depends on
recursively. The <literal>SCHEMA</> option will be propagated that are not already installed. Their dependencies are likewise
to the required extensions. Other options are not recursively automatically installed, recursively. The <literal>SCHEMA</> clause,
applied when using this clause. if given, applies to all extensions that get installed this way.
Other options of the statement are not applied to
automatically-installed extensions; in particular, their default
versions are always selected.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>