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

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

@ -335,11 +335,13 @@
by <application>pg_dump</>. Such a change is usually only sensible if
you concurrently make the same change in the extension's script file.
(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>
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>
statements. The final set of privileges for each object (if any are set)
will be stored in the
@ -453,9 +455,11 @@
<term><varname>comment</varname> (<type>string</type>)</term>
<listitem>
<para>
A comment (any string) about the extension. Alternatively,
the comment can be set by means of the <xref linkend="sql-comment">
command in the script file.
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
a <xref linkend="sql-comment"> command in the script file.
</para>
</listitem>
</varlistentry>
@ -518,7 +522,7 @@
its contained objects into a different schema after initial creation
of the extension. The default is <literal>false</>, i.e. the
extension is not relocatable.
See below for more information.
See <xref linkend="extend-extensions-relocation"> for more information.
</para>
</listitem>
</varlistentry>
@ -529,7 +533,10 @@
<para>
This parameter can only be set for non-relocatable extensions.
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>
</listitem>
</varlistentry>
@ -562,7 +569,8 @@
comments) by the extension mechanism. This provision is commonly used
to throw an error if the script file is fed to <application>psql</>
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, a state of affairs that's a bit tedious to recover from.
</para>
@ -580,7 +588,7 @@
</sect2>
<sect2>
<sect2 id="extend-extensions-relocation">
<title>Extension Relocatability</title>
<para>
@ -678,7 +686,7 @@ SET LOCAL search_path TO @extschema@;
</para>
</sect2>
<sect2>
<sect2 id="extend-extensions-config-tables">
<title>Extension Configuration Tables</title>
<para>
@ -762,7 +770,7 @@ SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entr
out but the dump will not be able to be restored directly and user
intervention will be required.
</para>
<para>
Sequences associated with <type>serial</> or <type>bigserial</> columns
need to be directly marked to dump their state. Marking their parent
@ -877,7 +885,7 @@ SELECT * FROM pg_extension_update_paths('<replaceable>extension_name</>');
</para>
</sect2>
<sect2>
<sect2 id="extend-extensions-example">
<title>Extension Example</title>
<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
schema either, the current default object creation schema is used.
</para>
<para>
If the extension specifies <literal>schema</> in its control file,
the schema cannot be overridden with <literal>SCHEMA</> clause.
The <literal>SCHEMA</> clause in this case works as follows:
<itemizedlist>
<listitem>
<para>
If <replaceable class="parameter">schema_name</replaceable> matches
the schema in control file, it will be used normally as there is no
conflict.
</para>
</listitem>
<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>
If the extension specifies a <literal>schema</> parameter in its
control file, then that schema cannot be overridden with
a <literal>SCHEMA</> clause. Normally, an error will be raised if
a <literal>SCHEMA</> clause is given and it conflicts with the
extension's <literal>schema</> parameter. However, if
the <literal>CASCADE</> clause is also given,
then <replaceable class="parameter">schema_name</replaceable> is
ignored when it conflicts. The
given <replaceable class="parameter">schema_name</replaceable> will be
used for installation of any needed extensions that do not
specify <literal>schema</> in their control files.
</para>
<para>
Remember that the extension itself is not considered to be within any
schema: extensions have unqualified names that must be unique
@ -147,7 +133,8 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name
<varlistentry>
<term><replaceable class="parameter">old_version</replaceable></term>
<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
an extension that replaces an <quote>old style</> module that is just
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>
<listitem>
<para>
Try to install extension including the required dependencies
recursively. The <literal>SCHEMA</> option will be propagated
to the required extensions. Other options are not recursively
applied when using this clause.
Automatically install any extensions that this extension depends on
that are not already installed. Their dependencies are likewise
automatically installed, recursively. The <literal>SCHEMA</> 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>
</listitem>
</varlistentry>