Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitbd180b6

Browse files
committed
Doc: minor documentation improvements about extensions.
Document the formerly-undocumented behavior that schema and commentcontrol-file entries for an extension are honored only during initialinstallation, whereas other properties are also honored during updates.While at it, do some copy-editing on the recently-added docs for CREATEEXTENSION ... 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 thiscould go further back, but they're probably not important enough tobother.
1 parent4f405c8 commitbd180b6

File tree

2 files changed

+42
-44
lines changed

2 files changed

+42
-44
lines changed

‎doc/src/sgml/extend.sgml‎

Lines changed: 20 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -335,11 +335,13 @@
335335
by <application>pg_dump</>. Such a change is usually only sensible if
336336
you concurrently make the same change in the extension's script file.
337337
(But there are special provisions for tables containing configuration
338-
data; see below.)
338+
data; see <xref linkend="extend-extensions-config-tables">.)
339+
In production situations, it's generally better to create an extension
340+
update script to perform changes to extension member objects.
339341
</para>
340342

341343
<para>
342-
The extension script may set privileges on objectswhich are part of the
344+
The extension script may set privileges on objectsthat are part of the
343345
extension via <command>GRANT</command> and <command>REVOKE</command>
344346
statements. The final set of privileges for each object (if any are set)
345347
will be stored in the
@@ -453,9 +455,11 @@
453455
<term><varname>comment</varname> (<type>string</type>)</term>
454456
<listitem>
455457
<para>
456-
A comment (any string) about the extension. Alternatively,
457-
the comment can be set by means of the <xref linkend="sql-comment">
458-
command in the script file.
458+
A comment (any string) about the extension. The comment is applied
459+
when initially creating an extension, but not during extension updates
460+
(since that might override user-added comments). Alternatively,
461+
the extension's comment can be set by writing
462+
a <xref linkend="sql-comment"> command in the script file.
459463
</para>
460464
</listitem>
461465
</varlistentry>
@@ -518,7 +522,7 @@
518522
its contained objects into a different schema after initial creation
519523
of the extension. The default is <literal>false</>, i.e. the
520524
extension is not relocatable.
521-
Seebelow for more information.
525+
See<xref linkend="extend-extensions-relocation"> for more information.
522526
</para>
523527
</listitem>
524528
</varlistentry>
@@ -529,7 +533,10 @@
529533
<para>
530534
This parameter can only be set for non-relocatable extensions.
531535
It forces the extension to be loaded into exactly the named schema
532-
and not any other. See below for more information.
536+
and not any other.
537+
The <varname>schema</varname> parameter is consulted only when
538+
initially creating an extension, not during extension updates.
539+
See <xref linkend="extend-extensions-relocation"> for more information.
533540
</para>
534541
</listitem>
535542
</varlistentry>
@@ -562,7 +569,8 @@
562569
comments) by the extension mechanism. This provision is commonly used
563570
to throw an error if the script file is fed to <application>psql</>
564571
rather than being loaded via <command>CREATE EXTENSION</> (see example
565-
script below). Without that, users might accidentally load the
572+
script in <xref linkend="extend-extensions-example">).
573+
Without that, users might accidentally load the
566574
extension's contents as <quote>loose</> objects rather than as an
567575
extension, a state of affairs that's a bit tedious to recover from.
568576
</para>
@@ -580,7 +588,7 @@
580588

581589
</sect2>
582590

583-
<sect2>
591+
<sect2 id="extend-extensions-relocation">
584592
<title>Extension Relocatability</title>
585593

586594
<para>
@@ -678,7 +686,7 @@ SET LOCAL search_path TO @extschema@;
678686
</para>
679687
</sect2>
680688

681-
<sect2>
689+
<sect2 id="extend-extensions-config-tables">
682690
<title>Extension Configuration Tables</title>
683691

684692
<para>
@@ -762,7 +770,7 @@ SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entr
762770
out but the dump will not be able to be restored directly and user
763771
intervention will be required.
764772
</para>
765-
773+
766774
<para>
767775
Sequences associated with <type>serial</> or <type>bigserial</> columns
768776
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</>');
877885
</para>
878886
</sect2>
879887

880-
<sect2>
888+
<sect2 id="extend-extensions-example">
881889
<title>Extension Example</title>
882890

883891
<para>

‎doc/src/sgml/ref/create_extension.sgml‎

Lines changed: 22 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -95,35 +95,21 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name
9595
If not specified, and the extension's control file does not specify a
9696
schema either, the current default object creation schema is used.
9797
</para>
98+
9899
<para>
99-
If the extension specifies <literal>schema</> in its control file,
100-
the schema cannot be overridden with <literal>SCHEMA</> clause.
101-
The <literal>SCHEMA</> clause in this case works as follows:
102-
<itemizedlist>
103-
<listitem>
104-
<para>
105-
If <replaceable class="parameter">schema_name</replaceable> matches
106-
the schema in control file, it will be used normally as there is no
107-
conflict.
108-
</para>
109-
</listitem>
110-
<listitem>
111-
<para>
112-
If the <literal>CASCADE</> clause is given, the
113-
<replaceable class="parameter">schema_name</replaceable> will only
114-
be used for the missing required extensions which do not specify
115-
<literal>schema</> in their control files.
116-
</para>
117-
</listitem>
118-
<listitem>
119-
<para>
120-
If <replaceable class="parameter">schema_name</replaceable> is not
121-
the same as the one in extension's control file and the
122-
<literal>CASCADE</> clause is not given, error will be thrown.
123-
</para>
124-
</listitem>
125-
</itemizedlist>
100+
If the extension specifies a <literal>schema</> parameter in its
101+
control file, then that schema cannot be overridden with
102+
a <literal>SCHEMA</> clause. Normally, an error will be raised if
103+
a <literal>SCHEMA</> clause is given and it conflicts with the
104+
extension's <literal>schema</> parameter. However, if
105+
the <literal>CASCADE</> clause is also given,
106+
then <replaceable class="parameter">schema_name</replaceable> is
107+
ignored when it conflicts. The
108+
given <replaceable class="parameter">schema_name</replaceable> will be
109+
used for installation of any needed extensions that do not
110+
specify <literal>schema</> in their control files.
126111
</para>
112+
127113
<para>
128114
Remember that the extension itself is not considered to be within any
129115
schema: extensions have unqualified names that must be unique
@@ -147,7 +133,8 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name
147133
<varlistentry>
148134
<term><replaceable class="parameter">old_version</replaceable></term>
149135
<listitem>
150-
<para><literal>FROM</> <replaceable class="parameter">old_version</>
136+
<para>
137+
<literal>FROM</> <replaceable class="parameter">old_version</>
151138
must be specified when, and only when, you are attempting to install
152139
an extension that replaces an <quote>old style</> module that is just
153140
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
174161
<term><literal>CASCADE</></term>
175162
<listitem>
176163
<para>
177-
Try to install extension including the required dependencies
178-
recursively. The <literal>SCHEMA</> option will be propagated
179-
to the required extensions. Other options are not recursively
180-
applied when using this clause.
164+
Automatically install any extensions that this extension depends on
165+
that are not already installed. Their dependencies are likewise
166+
automatically installed, recursively. The <literal>SCHEMA</> clause,
167+
if given, applies to all extensions that get installed this way.
168+
Other options of the statement are not applied to
169+
automatically-installed extensions; in particular, their default
170+
versions are always selected.
181171
</para>
182172
</listitem>
183173
</varlistentry>

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp